enlightenment
/
enlightenment
9
8
Fork 12
Code Issues 22 Pull Requests 1 Projects Releases Wiki Activity

Created a documentation skeleton and changed the comments in iconbar.c

Browse Source 
so that they're useful for the documentation system.


SVN revision: 5547
devs/princeamd/enlightenment-0.17-elive
cpk 22 years ago committed by cpk
parent 1a24c75a76
commit 79ef2ccbe9
2 changed files with 115 additions and 224 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 263
      doc/manual.raw
  2. 76
      src/iconbar.c

263
doc/manual.raw
Unescape View File

@ -1,20 +1,19 @@
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
<!ENTITY efsd "<function>efsd</function>">
<!ENTITY e17 "<productname>Enlightenment 0.17</productname>">
]>
<book id="efsd-documentation-howto">
<bookinfo>
<title>Enlightenment Documentation Howto</title>
<title>The Enlightenment 0.17 Manual</title>
<authorgroup>
<author>
<firstname>FIRSTNAME</firstname>
<othername>OTHER</othername>
<surname>LASTNAME</surname>
<firstname>Christian</firstname>
<surname>Kreibich</surname>
<affiliation>
<address>
<email>EMAIL</email>
<email>cK@whoop.org</email>
</address>
</affiliation>
</author>
@ -61,223 +60,73 @@
<chapter id="introduction">
<title>Introduction</title>
<para>
This is some sample documentation for you project. You'll need to be
familiar with <ulink url="http://docbook.org">DocBook</ulink>
to make best use of Enlightenment's documentation scheme.
This document explains the &e17; release, for both users and
developers.
</para>
<para>
See <link linkend="files" endterm="files.title"></link>
for an explanation of the documentation setup in you project.
</para>
<para>
<link linkend="comments" endterm="comments.title"></link> explains
the way you have to structure your comments so that they can be
extracted.
</para>
<para>
<link linkend="samples" endterm="samples.title"></link> contains a few
layout and markup examples to get you up to speed quickly.
</para>
</chapter>
<chapter id="files">
<title id="files.title">Documentation File Structure</title>
<para>
The entire documentation setup lives in the <filename>doc</filename>
directory. The file you need to edit is called <filename>manual.raw</filename>.
When you enter <command>make docs</command> 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 <command>!I&lt;filename&gt;</command>. Here,
<filename>filename</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.
</para>
<para>
The resulting file of that step is called <filename>$PACKAGE-manual-$VERSION.sgml</filename>
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.
</para>
<para>
Suppport for HTML generation is included already through the
<command>make html-docs</command> target. In order to be able to use
that, you'll need to have <command>jade</command> installed, and appropriate
DocBook stylesheets. If the <command>configure</command> script doesn't automatically find
you stylesheets (on a Debian system it should), you can specify them when
calling <command>configure</command> or <command>autogen.sh</command> using
the <command>--with-dbsheets=DIR</command> option.
</para>
<para>
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.
</para>
</chapter>
<chapter id="comments">
<title id="comments.title">Writing Extractable Comments</title>
<chapter id="using">
<title>Using &e17;</title>
<para>
I'll simply give an example of a commented function here:
<programlisting>
/**
* 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);
</programlisting>
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:
<itemizedlist mark="opencircle">
<listitem>
<para><command>funcname()</command> for function names</para>
</listitem>
<listitem>
<para><command>$ENVVAR</command> for environment variables</para>
</listitem>
<listitem>
<para><command>&amp;struct_name</command> for structures</para>
</listitem>
<listitem>
<para><command>%CONST</command> for constants/para>
</listitem>
</itemizedlist>
Here's how you use &e17;.
</para>
</chapter>
<chapter id="samples">
<title id="samples.title">DocBook Examples</title>
<section>
<title>Lists</title>
<section id="wm">
<title id="wm.title">The Window Manager</title>
<para>
<itemizedlist mark="opencircle">
<listitem>
<para>This</para>
</listitem>
<listitem>
<para>is</para>
</listitem>
<listitem>
<para>a</para>
</listitem>
<listitem>
<para>list</para>
</listitem>
</itemizedlist>
</para>
</section>
<section>
<title>Code</title>
<section id="fm">
<title id="fm.title">The File Manager</title>
<para>
<programlisting>
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. */
}
</programlisting>
</para>
</section>
<section>
<title>Images</title>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="figures/sampleimage.eps" format="eps">
</imageobject>
<imageobject>
<imagedata fileref="figures/sampleimage.gif" format="gif">
</imageobject>
<textobject>
<phrase>Sample image</phrase>
</textobject>
<caption>
<para>This is how you display images.</para>
</caption>
</mediaobject>
</chapter>
</para>
<chapter id="inside">
<title>Inside &e17;</title>
<para>
This chapter explains the inner workings of &e17;.
</para>
<section id="architecture">
<title id="architecture.title">&e17; Architecture</title>
<section id="overall">
<title id="overall.title">Overview</title>
<para>
</para>
</section>
<section id="modules">
<title id="modules.title">Modules</title>
<para>
</para>
</section>
</section>
<section>
<title>Warnings, Notes</title>
<para>
<note>
<title>This is an example of a note.</title>
<para>
It's really simple to use.
</para>
</note
</para>
<para>
<caution>
<title>This is a warning.</title>
<para>
It's used just like a note.
</para>
</caution>
</para>
<section id="concepts">
<title id="concepts.title">Themeing</title>
<section id="overview">
<title id="overview.title">Overview</title>
<para>
</para>
</section>
<section id="system">
<title id="system.title">System Settings</title>
<para>
</para>
</section>
<section id="user">
<title id="user.title">User Settings</title>
<para>
</para>
</section>
</section>
<section id="code">
<title>Code Documentation</title>
!Isrc/iconbar.c
</section>
</chapter>
<bibliography>
<biblioentry id="bib-unp">
<bookbiblio>
<author>
<firstname>W. R.</firstname>
<surname>Stevens</surname>
</author>
<title>UNIX Network Programming</title>
<edition>Second Edition</edition>
<volumenum>Volume 1</volumenum>
<publisher>
<publishername>Prentice-Hall</publishername>
</publisher>
<date>1998</date>
</bookbiblio>
</biblioentry>
<biblioentry id="bib-apue">
<bookbiblio>
<author>
<firstname>W. R.</firstname>
<surname>Stevens</surname>
</author>
<title>Advanced Programming in the UNIX Environment</title>
<publisher>
<publishername>Addison-Wesley</publishername>
</publisher>
<date>1992</date>
</bookbiblio>
</biblioentry>
</bibliography>
</book>

76
src/iconbar.c
Unescape View File

@ -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 */

Write Preview
Loading…
Cancel
Save