From 79ef2ccbe9e8e32e350bc7e822efcb7d5671a57b Mon Sep 17 00:00:00 2001 From: cpk Date: Sun, 21 Oct 2001 22:03:36 +0000 Subject: [PATCH] Created a documentation skeleton and changed the comments in iconbar.c so that they're useful for the documentation system. SVN revision: 5547 --- doc/manual.raw | 269 +++++++++++-------------------------------------- src/iconbar.c | 76 ++++++++++---- 2 files changed, 118 insertions(+), 227 deletions(-) diff --git a/doc/manual.raw b/doc/manual.raw index 65d9325a2..a711f2304 100644 --- a/doc/manual.raw +++ b/doc/manual.raw @@ -1,20 +1,19 @@ efsd"> +Enlightenment 0.17"> ]> - Enlightenment Documentation Howto + The Enlightenment 0.17 Manual - FIRSTNAME - OTHER - LASTNAME + Christian + Kreibich
- EMAIL + cK@whoop.org
@@ -61,223 +60,73 @@ Introduction - This is some sample documentation for you project. You'll need to be - familiar with DocBook - to make best use of Enlightenment's documentation scheme. - - - See - for an explanation of the documentation setup in you project. - - - explains - the way you have to structure your comments so that they can be - extracted. - - - contains a few - layout and markup examples to get you up to speed quickly. + This document explains the &e17; release, for both users and + developers. - - Documentation File Structure + + Using &e17; - The entire documentation setup lives in the doc - directory. The file you need to edit is called manual.raw. - When you enter make docs in the toplevel directory, - it gets translated into a standard SGML file using a Perl script. - The script scans the file for any lines starting directly with the - string !I<filename>. Here, - filename is the name of a code - file in which you have put extractable comments. The Perl script will - then analyze the file and generate SGML DocBook statements for those - comments right into the output file. + Here's how you use &e17;. - - The resulting file of that step is called $PACKAGE-manual-$VERSION.sgml - where PACKAGE and VERSION are automatically set during the build process. - This sgml file can be postprocessed with any SGML processor to generate - for example HTML, TeX or PDF output. - - - Suppport for HTML generation is included already through the - make html-docs target. In order to be able to use - that, you'll need to have jade installed, and appropriate - DocBook stylesheets. If the configure script doesn't automatically find - you stylesheets (on a Debian system it should), you can specify them when - calling configure or autogen.sh using - the --with-dbsheets=DIR option. - - - If everything worked out fine, you'll get a tarball of the HTML version - of your documentation and the extracted version in the docs directory, - named similarly to the SGML file. - - + +
+ The Window Manager + + +
+ +
+ The File Manager + + +
- - Writing Extractable Comments + + Inside &e17; - I'll simply give an example of a commented function here: - - - -/** - * efsd_wait_event - blocking wait for next Efsd event. - * @ec: The Efsd connection - * @ev: Pointer to an allocated EfsdEvent. - * - * Blocks until an efsd event arrives, then returns it by filling - * in the @ev structure. Returns -1 when there was an error, - * >= 0 otherwise. - */ -int efsd_wait_event(EfsdConnection *ec, EfsdEvent *ev); - - As you can see, it's not hard -- just use two asterisks - to signal the start of an extractable comment. In the first - line, begin with the function name and a one-liner description. - Then, put each parameter in the following lines. Add an empty - line, and then a more verbose description. That's basically - it, you can also markup items differently as follows: - - - - funcname() for function names - - - $ENVVAR for environment variables - - - &struct_name for structures - - - %CONST for constants/para> - - + This chapter explains the inner workings of &e17;. - - - - DocBook Examples -
- Lists - - - - This - - - is - - - a - - - list - - - +
+ &e17; Architecture +
+ Overview + + +
+
+ Modules + + +
-
- Code - - - -EfsdConnection *ec; - -if ( (ec = efsd_open()) == NULL) - { - /* Oops. Couldn't establish connection. - * Is Efsd really running ? - */ - } - -/* ... various efsd commands ... */ - -if (efsd_close(ec) < 0) - { - /* Ouch. Error when closing connection. */ - } - - + +
+ Themeing +
+ Overview + + +
+
+ System Settings + + +
+
+ User Settings + + +
-
- Images - - - - - - - - - - - Sample image - - - This is how you display images. - - - - -
-
- Warnings, Notes - - - This is an example of a note. - - It's really simple to use. - - - - - This is a warning. - - It's used just like a note. - - - + +
+ Code Documentation +!Isrc/iconbar.c
- - - - - - W. R. - Stevens - - UNIX Network Programming - Second Edition - Volume 1 - - Prentice-Hall - - 1998 - - - - - - - W. R. - Stevens - - Advanced Programming in the UNIX Environment - - Addison-Wesley - - 1992 - - - - - diff --git a/src/iconbar.c b/src/iconbar.c index a34513db2..4435464ad 100644 --- a/src/iconbar.c +++ b/src/iconbar.c @@ -32,7 +32,11 @@ static void ib_mouse_up(void *data, Evas _e, Evas_Object _o, int _b, int _x, int /* please feel free to add to them to make them easier to read and be more */ /* helpful. */ -/* init function - initialised the iconbar system */ +/** + * e_iconbar_init - Init function + * + * Initialises the iconbar system + */ void e_iconbar_init() { @@ -57,7 +61,10 @@ e_iconbar_init() E_CONFIG_NODE(cf_iconbar, "icons", E_CFG_TYPE_LIST, cf_iconbar_icon, E_Iconbar, icons, 0, 0, NULL); } -/* how do we crate a new iconbar? well... like this! */ +/** + * e_iconbar_new - Iconbar constructor + * @v: The view for which an iconbar is to be constructed + */ E_Iconbar * e_iconbar_new(E_View *v) { @@ -111,7 +118,12 @@ e_iconbar_new(E_View *v) return ib; } -/* our free method for iconbars. how do we free these pesky little urchins */ +/** + * e_iconbar_free - Iconbar destructor. + * @ib: The iconbar to be freed + * + * How do we free these pesky little urchins... + */ void e_iconbar_free(E_Iconbar *ib) { @@ -145,7 +157,10 @@ e_iconbar_free(E_Iconbar *ib) FREE(ib); } -/* how do we free an iconbar icon... well like this */ +/** + * e_iconbar_icon_free -- Iconbar icon destructor + * @ic: The icon that is to be freed + */ void e_iconbar_icon_free(E_Iconbar_Icon *ic) { @@ -165,8 +180,14 @@ e_iconbar_icon_free(E_Iconbar_Icon *ic) FREE(ic); } - /* turn our iconbar into more than a structure of config data. actually */ - /* crate evas objcts we can do something visual with */ +/** + * e_iconbar_realize - Iconbar initialization. + * @ib: The iconbar to initalize + * + * Turns an iconbar into more than a + * structure of config data -- actually create evas objcts + * we can do something visual with + */ void e_iconbar_realize(E_Iconbar *ib) { @@ -200,7 +221,7 @@ e_iconbar_realize(E_Iconbar *ib) ebits_add_to_evas(ib->bit, ib->view->evas); /* aaaaaaaaah. the magic of being able to replace a named bit in an ebit */ /* (in this case we expect a bit called "Icons" to exist - the user will */ - /* have added a bti called this into the ebit to indicate where he/she */ + /* have added a bit called this into the ebit to indicate where he/she */ /* wants icons to go. we basically replace this bit with a virtual set */ /* of callbacks that ebits will call if this bit is to be moved, resized */ /* shown, hidden, raised, lowered etc. we provide the callbacks. */ @@ -225,7 +246,13 @@ e_iconbar_realize(E_Iconbar *ib) e_iconbar_fix(ib); } -/* fix up the geometry and visibility of the iconbar gfx and icons */ +/** + * e_iconbar_fix - iconbar geometry update + * @ib: The iconbar for which to fix the geometry + * + * This function corrects the geometry and visibility + * of the iconbar gfx and icons + */ void e_iconbar_fix(E_Iconbar *ib) { @@ -315,9 +342,16 @@ e_iconbar_fix(E_Iconbar *ib) } } -/* this function is called from the view code whenever a file is added to a */ -/* view. the iconbar code here determines if the file add is of interest */ -/* and if it is, in 0.5 secs will do a "reload */ +/** + * e_iconbar_file_add - Adds a file to a view + * @v: The view in which a file is added + * @file: Name of the added file + * + * This function is called from the + * view code whenever a file is added to a view. The iconbar code here + * determines if the file add is of interest + * and if it is, in 0.5 secs will do a "reload + */ void e_iconbar_file_add(E_View *v, char *file) { @@ -334,7 +368,13 @@ e_iconbar_file_add(E_View *v, char *file) } } -/* caled whenever a file is deleted from a view */ +/** + * e_iconbar_file_delete - Function to remove a file from an iconbox. + * @v: The view in which a file is removed + * @file: Name of the removed file + * + * This function is called whenever a file is deleted from a view. + */ void e_iconbar_file_delete(E_View *v, char *file) { @@ -352,7 +392,13 @@ e_iconbar_file_delete(E_View *v, char *file) } } -/* called whenever a file changes in a view */ +/** + * e_iconbar_file_change - File change update function + * @v: The view in which a file changes + * @file: Name of the changed file + * + * This function gets called whenever a file changes in a view + */ void e_iconbar_file_change(E_View *v, char *file) { @@ -371,10 +417,6 @@ e_iconbar_file_change(E_View *v, char *file) - - - - /* static (internal to iconbar use only) callbacks */ /* reload timeout. called whenevr iconbar special files changed/added to */