efsd"> ]> FIRSTNAME OTHER LASTNAME

EMAIL

2001 Christian Kreibich Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies of the Software and its documentation and acknowledgment shall be given in the documentation and software packages that this Software was used. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. This is document is nowhere near being finished. Be patient. 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. 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. 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. 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 is a list

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. */ }

Sample image This is how you display images.

It's really simple to use. It's used just like a note.

W. R. Stevens Second Edition Volume 1 Prentice-Hall 1998 W. R. Stevens Addison-Wesley 1992