aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--doc/manual.raw263
-rw-r--r--src/iconbar.c76
2 files changed, 115 insertions, 224 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 @@
<!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>
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 */