Re: [AD] Documentation proposition

["Eric Botcazou" <ebotcazou@xxxxxxxxxx>]

> Ok, see this version of the patch.

I've attached a reworked version of the ahack._tx stuff (not in diff format
because diffs of diffs are barely readable). Feel free to modify it again.

One remark: why did you turn e.g. into i.e.? They don't have the same
meaning, and most of the time the right one is e.g.


For the allegro._tx patch:

@@ -90,7 +90,8 @@
    Initialises the Allegro library. You must call either this or
    allegro_init() before doing anything other than using the Unicode
    routines. If you want to use a text mode other than UTF-8, you can set
-   it with set_uformat() before you call this.
+   it with set_uformat() before you call this. Other functions which can be
+   called before this will be marked explicitly in the documentation.

I'd say "The other functions that can be called before this one will be..."
to emphasize the completeness.


@@ -104,9 +105,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.
-
-   This function returns zero on success and non-zero on failure (e.g. no
+   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 (ie. no
    system driver could be used). Note: in previous versions of Allegro this
    function would abort on error.

Bad formatting for <endblock>? And this is e.g.


@@ -212,22 +216,29 @@
    a text console (DOS and Unix) it will print the string to that console,
    attempting to work around codepage differences by reducing any accented
    characters to 7-bit ASCII approximations, and on platforms featuring a
-   windowing system it will bring up a GUI message box.
-
+   windowing system it will bring up a GUI message box. msg should be in
the
+   text encoding format previously set by set_uformat(). Example:
+<codeblock>
+      ret = allegro_init();
+      if (ret != 0) {
+  allegro_message("Sorry, couldn't init Allegro (%d).\n", ret);
+  exit(ret);
+      }
+<endblock>

The blurb about 'msg' is superfluous: all strings passed to API functions
must be in the format previously set by set_uformat(), unless stated
otherwise.


 @@void @set_window_title(const char *name);
-@domain.hid set_close_button_callback
+@xref set_close_button_callback, set_uformat
 @eref exunicod
    On platforms that are capable of it, this routine alters the window
title
    for your Allegro program. Note that Allegro cannot set the window title
-   when running in a DOS box under Windows.
+   when running in a DOS box under Windows. msg should be in the text
+   encoding format previously set by set_uformat().

Likewise.


+@retval
+   Returns zero on success and non-zero on failure (ie. the feature is not
+   supported by the platform).

This is e.g. again.


+@xref get_desktop_resolution, set_color_depth, set_gfx_mode
+   Finds out the currently selected desktop color depth. You can use this
+   information to make your program use the same color depth as the
desktop,
+   which will likely make your program run faster because the graphic
driver

...make it...

+   won't be doing unnecessary color conversions behind your back. Usually
you
+   want to call this before setting the graphic mode. Example:
+<codeblock>
+      allegro_init();
+      ...
+      if ((depth = desktop_color_depth())) {
+  set_color_depth(depth);
+      }<endblock>

Bad formatting for <endblock>? And the example is error-prone, add '!=0'

+@retval
+   Returns zero on platforms where this information is not available or
does
+   not apply, or the color depth (like 8, 16, etc).

Returns the color depth -- no random values or all values -- or zero on...


+   to create windows bigger than the desktop. Each parameter is a pointer
+   to an integer you have to provide, where the screen sizes will be
stored.

Each parameter is a pointer to an integer where one dimension of the screen
will be stored.

+<codeblock>
+      int width, height;
+      allegro_init();
+      ...
+      if (get_desktop_resolution(&width, &height) == 0) {
+  /* Got the resolution correctly */
+      }<endblock>

Space before allegro_init(). Bad formatting for <endblock>?


+@xref vsync
+   Due to the polling nature of Allegro, even if your program is not doing
+   much, other programs monitoring CPU usage will likely say that your
+   Allegro process consumes nearly 100% of the CPU. This is inevitable:
+   polling the keys, checking mouse coordinates or just updating the screen
+   are operations which will fire up CPU consumption.

I don't like this paragraph very much: Allegro is not a polling library. For
example, under Windows, all the auxilliary threads are blocking so, given
that readkey() is blocking on that platform too, you can have an Allegro
program blocking on the keyboard input. The true reason is simply that a
thread that is not blocking can be given 100% of the CPU by the scheduler
(like with while(1);). So, as long as you program does something (i.e
doesn't block), it can be given 100% of the CPU.

+   To "play nice" with other processes you can call this function. On
+   systems that support this it will give up the rest of the current

support it, it will...

+   scheduler timeslice and offer it to some other process. This will drop

...other processes.

+   your CPU consumption rate *only* if there is another process ready to
+   take posession of the freed timeslice.

Your CPU consumption rate will drop *only* if there is another process ready
to use the freed timeslice.

+   Note that calling this inside your active game loop is a bad idea, you

...a very bad idea...

+   never know when the OS will give you the CPU back, and hence you could
+   end up missing the vertical retrace and skip frames.

, so you could...and skipping frames.


+   char * as a parameter. type should be one of these values:

"type" must be quoted (or something like that).


   Finds out what text encoding format is currently selected. This function
+   is probably useful only if you are writting an Allegro addon dealing
with
+   text strings and you require different specific code for each one of the
+   possibilities. Example:

... writing... and you use a different codepath for each possible format.


+   Returns the currently selected text encoding format as an integer. See
the
+   documentation of set_uformat for a list of encoding formats.

'as an integer' is superfluous.


+<codeblock>
+      if (need_uconvert(text, U_UTF8, U_CURRENT)) {
+  /* conversion is required */
+      }<endblock>

Bad formatting for <endblock>?

+@retval
+   Returns zero if no conversion is needed, non zero otherwise.

Returns non-zero if any conversion is required or zero otherwise.


+   Finds out how many bytes are would be required to store the specified

...are...


+   Note that even for empty strings your destination string must have at

Note that, even for empty strings, your...


+   least enough bytes to store the NULL terminator character of the string,

Did you watch T3 recently? :-)  "the terminating null character"


+   and your parameter size must reflect this. Otherwise, the debug version
of
+   Allegro will abort at an assertion, and the release version of Allegro
+   will produce a buffer overflow past the end of the destination string.

will overrun the destination buffer.


+   bytes into the output buf (including NULL terminator), but it checks

the terminating null character (!= NULL pointer).


+   before doing the conversion, and doesn't bother if the string formats
are
+   already the same (either both types are equal, or one is ASCII, the
other
+   is UTF-8, and the string contains only 7-bit ASCII characters).

+@retval
+   Returns a pointer to buf (or the static buffer if you used NULL) if a
+   conversion was performed. Otherwise it returns a copy of s, so you must

Otherwise returns a copy of s. In any cases, you should...


-   default input is the mouse. If the device has only one tool (e.g. a
+   default input is the mouse. If the device has only one tool (ie. a

This is e.g.


+   /dev/audio, but could be a particular device (ie. /dev/dsp2).

Likewise.


+   operate on files without explicitly using packfiles (ie. load_bitmap()).

Likewise.


+   application (ie. crash it) or even block your OS.

Likewise.


+   that some Allegro functions are blocking (ie. readkey() if the key
buffer

Likewise.


--
Eric Botcazou

Attachment: ahack.diff
Description: Binary data