Re: [AD] First batch of doc changes

[Peter Wang <tjaden@xxxxxxxxxx>]

On 2005-06-05, Evert Glebbeek <eglebbk@xxxxxxxxxx> wrote:
> I'm going to post my proposed documentation changes section for section, 
> otherwise I'm afraid it's going to be too much to look at each section.
> Attached is my first proposal for the `Using Allegro' section. It documents 
> some hither-to undocumented (but public and in one case even mentioned) 
> macros and adds a few simple examples.
> 
> Evert

> +@@Macro @MAKE_VERSION(a, b, c)
> +@shortdesc Create a 32 bit integer from the Allegro version
> +@xref ALLEGRO_VERSION, ALLEGRO_SUB_VERSION, ALLEGRO_WIP_VERSION
> +   This macro can be used to check if some Allegro version is (binary)
> +   compatible with the current version. It is safe to use &gt; and &lt; to

Those should be &gt and &lt (without the semicolons).

> +   check if one version is more recent than another. This is mainly useful for 
> +   addon packages and libraries. See the `ABI compatibility information'
> +   section of the manual for more detailed information. Example:
> +<codeblock>
> +      /* Check if the current version is compatible with Allegro 4.2.0 */
> +      #if (MAKE_VERSION(4, 2, 0) == MAKE_VERSION(ALLEGRO_VERSION, \
> +                         ALLEGRO_SUB_VERSION, ALLEGRO_WIP_VERSION))
> +         /* Allegro 4.2.0 compatibility */
> +      #else
> +         /* Work-around */
> +      #endif<endblock>
> +   

I thought the example was wrong, but actually the doc is missing
something like:

   The third number is ignored if the second number is even, so
   MAKE_VERSION(4, 2, 0) is equivalent to MAKE_VERSION(4, 2, 1).
   This is due to our version numbering policy since 4.0.0.
   The second number is even for stable releases, which to be
   ABI-compatible with earlier versions of the same series.

I'm not sure if MAKE_VERSION should be considered public, and if it is,
I'm not sure that the behaviour described above is good.  I understand
Chris needed that behaviour for his version checking patch, but that
should not determine the public interface.

Also, consider changing == in the example to <=.

>  @@int @set_close_button_callback(void (*proc)(void));
>  @xref set_window_title
...
> +      int main(void)
> +      {
> +         allegro_init();
> +         LOCK_FUNCTION(close_button_handler);
> +         set_close_button_callback(close_button_handler);
> +         ...
> +         
> +         while(close_button_pressed == FALSE) {

As per Allegro style, add a space after `while'.  And
"while (!close_button_pressed)" reads better, so long as you
read ! as not :-)

The rest looked fine.

Peter