Re: [AD] Documentation update

[Peter Wang <tjaden@xxxxxxxxxx>]

[Sorry about the lack of formatting.]

On Thursday 20 January 2005 08:06 am, Grzegorz Adam Hankiewicz wrote:
> Proposed documentation update attached.

@@ -5209,6 +5215,8 @@
    colors as the input to draw_trans_sprite() or draw_trans_rle_sprite()
    after calling set_alpha_blender(), rather than drawing them directly to
    the screen.
+@retval
+   Returns the requested RGBA triplet.


Should be "RGBA quartet".


 @@fixed @fixsub(fixed x, fixed y);
 @xref fixadd, fixmul, fixdiv
+@shortdesc Safe function to substract fixed point numbers without overflow.
    Fixed point subtraction: see comments about fixadd().

 @hnode Fixed point trig

"substract" -> "subtract"

I think the "without overflow" is misleading, but I don't know what to replace 
it with.


@@ -10040,16 +10119,19 @@

 @@int @d_clear_proc(int msg, DIALOG *d, int c);
 @eref excustom, exgui
+@shortdesc Dialog to clear the screen.
    This just clears the screen when it is drawn. Useful as the first object
    in a dialog.

 @@int @d_box_proc(int msg, DIALOG *d, int c);
 @@int @d_shadow_box_proc(int msg, DIALOG *d, int c);
 @eref exgui, exrgbhsv
+@shortdesc Dialog drawing boxes onto the screen.
    These draw boxes onto the screen, with or without a shadow.

 @@int @d_bitmap_proc(int msg, DIALOG *d, int c);
 @eref exgui, exrgbhsv
+@shortdesc Dialog drawing a bitmap.
    This draws a bitmap onto the screen, which should be pointed to by the
    dp field.

"Dialog procedure to ..." would be better.


@@ -10067,6 +10150,7 @@

 @@int @d_button_proc(int msg, DIALOG *d, int c);
 @eref excustom, exgui
+@shortdesc A button object.
    A button object (the dp field points to the text string). This object can
    be selected by clicking on it with the mouse or by pressing its keyboard
    shortcut. If the D_EXIT flag is set, selecting it will close the dialog,

Where are these shortdesc's used?  A bit more context might be good, such as 
"A dialog procedure implementing a button object".


@@ -10459,6 +10583,7 @@
 @\extern void (*@gui_menu_draw_menu_item)(MENU *m, int x, int y, int w,
 @@                                       int h, int bar, int sel);
 @xref GUI menus
+@shortdesc Hooks to modify the outlook of menus.
    If set, these functions will be called whenever a menu needs to be
    drawn, so you can change how menus look.

outlook -> appearance.  Outlook has to do with looking to the future.


@@ -10535,6 +10665,7 @@
 @\int @gfx_mode_select_filter(int *card, int *w, int *h, int *color_depth,
 @@                            int (*filter)(int, int, int, int));
 @xref gfx_mode_select, gfx_mode_select_ex, set_color_depth, set_gfx_mode, 
gui_fg_color
+@shortdesc Even more extender version of the graphics mode selection dialog.
    Even more extended version of the graphics mode selection dialog, which
    allows the programmer to customize the contents of the dialog and the user
    to select the color depth as well as the resolution and hardware driver.

extender -> extended


Good work!

Peter