[AD] Documentation proposition

[Grzegorz Adam Hankiewicz <gradha@xxxxxxxxxx>]

Eric, things like this on the stable branch too?

Index: docs/src/ahack._tx
===================================================================
RCS file: /cvsroot/alleg/allegro/docs/src/ahack._tx,v
retrieving revision 1.8
diff -u -r1.8 ahack._tx
--- docs/src/ahack._tx	23 Jan 2003 20:53:41 -0000	1.8
+++ docs/src/ahack._tx	22 Jul 2003 20:56:56 -0000
@@ -335,6 +335,51 @@
 
 
 @heading
+Documentation
+
+One of the nicest thing of Allegro is the excellent manual which you can read
+in several file formats, ranging from plain text to compiled HTML. All
+userland functions have to be documented in docs/src/allegro._tx in their
+correct section. Note that whatever you write you shouldn't exceed a width of
+78 characters, with the exception of lines which contain HTML tags. This is
+to have a correct plain text documentation which doesn't come out of the
+standard 80 column screen/terminal. All the other formats are less tight
+about text width, and they will probably reformat it anyway.
+
+If the function you are documenting has a return value, use the @retval
+command to start the chunk of text which explains the return value or how it
+is used. If the function has parameters, indicate if they are required to
+follow a specific format (ie: string encoding), what are they used for, and
+never forget to say the accepted range of values for a parameter if any. The
+latter is particularily important with boolean parameters, because there's no
+way to say in C to the user that an integer can be either true or false.
+
+If it is possible, include as an example a little fragment of code which
+shows the usage of the function in a real life environment. Usually a single
+line will be enough, but don't hesitate to write around whatever comments you
+might think of as useful for newbie users. Also, if you are writting such a
+one liner, try to use verbose variable names to indicate where they come from
+or what they should contain. Compare the following lines, where the second is
+more likely to be found in `real life' code, but should be avoided in the
+examples:
+<textblock>
+    blit(source_bitmap, destination_bitmap, source_x, source_y,
+        destination_x, destination_y, bitmap_width, bitmap_height);
+    ...
+    blit(spr[3]->bmp, screen, x, y, s_x, s_y, spr[3]->bmp->w, spr[3]->bmp->h);
+<endblock>
+Don't bother about existing @eref commands. These are generated automatically
+with a script. The person in charge of releasing Allegro will most surely do
+this for you. If you know how to run it, though, you are welcome to update
+these tags too, to avoid piling extra work on the maintainer.
+
+Whatever coding style applies to Allegro code is also applied to documented
+examples (ie: 8 character tab stops). Of course, all said about documenting
+functions applies to macros and variables too.
+
+
+
+@heading
 Other Stuff
 
 Any portable routines that run inside a timer handler or input callback must 
Index: docs/src/allegro._tx
===================================================================
RCS file: /cvsroot/alleg/allegro/docs/src/allegro._tx,v
retrieving revision 1.172
diff -u -r1.172 allegro._tx
--- docs/src/allegro._tx	12 Jul 2003 11:58:14 -0000	1.172
+++ docs/src/allegro._tx	22 Jul 2003 20:57:46 -0000
@@ -104,8 +104,11 @@
    and atexit function from your libc: these are required because when
    Allegro is linked as a DLL, it doesn't have direct access to your local
    libc data.  atexit_ptr may be NULL, in which case it is your
-   responsibility to call allegro_exit() manually.
-
+   responsibility to call allegro_exit() manually. Example:
+<codeblock>
+      install_allegro(SYSTEM_AUTODETECT, &errno, atexit);
+<endblock>
+@retval
    This function returns zero on success and non-zero on failure (e.g. no
    system driver could be used). Note: in previous versions of Allegro this
    function would abort on error.