From c6e78c57fc1b323ec055bfe48c7430515be27d1c Mon Sep 17 00:00:00 2001 From: Philip Chimento Date: Wed, 28 Apr 2010 23:26:13 +0000 Subject: [PATCH] Fixed documentation to work with Gtk-Doc 1.14 and produce as few warnings as possible git-svn-id: http://lassie.dyndns-server.com/svn/gargoyle-gtk@246 ddfedd41-794f-dd11-ae45-00112f111e67 --- docs/reference/Makefile.am | 5 +- docs/reference/chimara-sections.txt | 11 ++ docs/reference/glk-other-events.sgml | 18 +-- docs/reference/glk-window-arrangement.sgml | 2 +- libchimara/chimara-glk.c | 13 +- libchimara/chimara-glk.h | 36 ++--- libchimara/chimara-if.h | 35 ++++- libchimara/dispatch.c | 42 ++--- libchimara/doc.c | 175 +++++++++++---------- libchimara/fileref.c | 2 +- libchimara/garglk.c | 2 +- libchimara/glk.c | 4 +- libchimara/glkunix.c | 4 +- libchimara/graphics.c | 2 +- libchimara/stream.c | 4 +- libchimara/window.c | 28 ++-- 16 files changed, 214 insertions(+), 169 deletions(-) diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am index 890de7d..ac9181d 100644 --- a/docs/reference/Makefile.am +++ b/docs/reference/Makefile.am @@ -51,8 +51,9 @@ CFILE_GLOB = $(top_srcdir)/libchimara/*.c EXTRA_HFILES = # Header files to ignore when scanning. Use base file name, no paths -IGNORE_HFILES = chimara-glk-private.h \ - abort.h charset.h event.h input.h stream.h window.h +IGNORE_HFILES = chimara-glk-private.h chimara-marshallers.h \ + abort.h charset.h event.h fileref.h graphics.h hyperlink.h init.h input.h \ + magic.h mouse.h pager.h resource.h stream.h strio.h style.h timer.h window.h # Images to copy into HTML directory. HTML_IMAGES = \ diff --git a/docs/reference/chimara-sections.txt b/docs/reference/chimara-sections.txt index fd9315a..3756d5a 100644 --- a/docs/reference/chimara-sections.txt +++ b/docs/reference/chimara-sections.txt @@ -575,6 +575,8 @@ giblorb_ID_Pict giblorb_ID_Copyright giblorb_ID_AUTH giblorb_ID_ANNO + +giblorb_make_id
@@ -602,6 +604,9 @@ glkunix_arg_ValueFollows glkunix_arg_ValueCanFollow glkunix_arg_NumberValue glkunix_arg_End + +glkunix_startup_code +NULL
@@ -610,3 +615,9 @@ glkunix_arg_End glkunix_stream_open_pathname glkunix_set_base_file
+ +
+glkext-garglk +Gargoyle Extensions +garglk_set_reverse_video +
\ No newline at end of file diff --git a/docs/reference/glk-other-events.sgml b/docs/reference/glk-other-events.sgml index b60a33f..02b4fbf 100644 --- a/docs/reference/glk-other-events.sgml +++ b/docs/reference/glk-other-events.sgml @@ -23,21 +23,21 @@ It is possible that new event types will be defined in the future. This is also why you must put calls to glk_select() in loops. If you tried to read a character by simply writing - -#glk_request_char_event(win); -#glk_select(&ev); - +|[ +glk_request_char_event(win); +glk_select(&ev); +]| you might not get a CharInput event back. You could get some not-yet-defined event which happened to occur before the player hit a key. Or, for that matter, a window arrangement event. It is not generally necessary to put a call to glk_select_poll() in a loop. You usually call glk_select_poll() to update the display or test if an event is available, not to wait for a particular event. However, if you are using sound notification events, and several sounds are playing, it might be important to make sure you knew about all sounds completed at any particular time. You would do this with - -#glk_select_poll(&ev); -while (ev.type != #evtype_None) { +|[ +glk_select_poll(&ev); +while (ev.type != evtype_None) { /* handle event */ - #glk_select_poll(&ev); + glk_select_poll(&ev); } - +]| Once glk_select_poll() returns #evtype_None, you should not call it again immediately. Do some work first. If you want to wait for an event, use glk_select(), not a loop of glk_select_poll(). diff --git a/docs/reference/glk-window-arrangement.sgml b/docs/reference/glk-window-arrangement.sgml index fe9f667..cc9ba52 100644 --- a/docs/reference/glk-window-arrangement.sgml +++ b/docs/reference/glk-window-arrangement.sgml @@ -30,7 +30,7 @@ Now you have two windows. In exactly the same way, you can split either of them You can repeat this as often as you want. Every time you split a window, one new window is created. Therefore, the call that does this is called glk_window_open(). -It might have been less confusing to call it glk_split_window() — or it might have been more confusing. I picked one. +It might have been less confusing to call it glk_split_window() — or it might have been more confusing. I picked one. It is important to remember that the order of splitting matters. If you split twice, you don't have a trio of windows; you have a pair with another pair on one side. Mathematically, the window structure is a binary tree. diff --git a/libchimara/chimara-glk.c b/libchimara/chimara-glk.c index 6384918..f561770 100644 --- a/libchimara/chimara-glk.c +++ b/libchimara/chimara-glk.c @@ -714,7 +714,8 @@ chimara_glk_class_init(ChimaraGlkClass *klass) * * Sets whether the widget is interactive. A Glk widget is normally * interactive, but in non-interactive mode, keyboard and mouse input are - * ignored and the Glk program is controlled by chimara_glk_feed_text(). + * ignored and the Glk program is controlled by + * chimara_glk_feed_char_input() and chimara_glk_feed_line_input(). * More prompts when a lot of text is printed to a text * buffer are also disabled. This is typically used when you wish to control * an interpreter program by feeding it a predefined list of commands. @@ -876,8 +877,8 @@ chimara_glk_set_css_to_default(ChimaraGlk *glk) * chimara_glk_set_css_from_file: * @glk: a #ChimaraGlk widget * @filename: path to a CSS file, or %NULL - * @error: location to store a GError, or - * %NULL + * @error: location to store a GError, or %NULL * * Sets the styles for text buffer and text grid windows according to the CSS * file @filename. Note that the styles are set cumulatively on top of whatever @@ -921,7 +922,7 @@ chimara_glk_set_css_from_file(ChimaraGlk *glk, const gchar *filename, GError **e /** * chimara_glk_set_css_from_string: * @glk: a #ChimaraGlk widget - * @filename: a string containing CSS code + * @css: a string containing CSS code * * Sets the styles for text buffer and text grid windows according to the CSS * code @css. Note that the styles are set cumulatively on top of whatever the @@ -1031,8 +1032,8 @@ glk_enter(struct StartupData *startup) * class="header">glk.h * @argc: Number of command line arguments in @argv * @argv: Array of command line arguments to pass to the plugin - * @error: location to store a GError, or - * %NULL + * @error: location to store a GError, or %NULL * * Opens a Glk program compiled as a plugin. Sorts out its command line * arguments from #glkunix_arguments, calls its startup function diff --git a/libchimara/chimara-glk.h b/libchimara/chimara-glk.h index b0709c0..75c7740 100644 --- a/libchimara/chimara-glk.h +++ b/libchimara/chimara-glk.h @@ -40,32 +40,18 @@ typedef struct _ChimaraGlkClass { /** * ChimaraError: + * @CHIMARA_LOAD_MODULE_ERROR: There was an error opening the plugin containing + * the Glk program. The error message from g_module_error() is appended to the GError message. + * @CHIMARA_NO_GLK_MAIN: The plugin containing the Glk program did not export a + * glk_main() function. + * @CHIMARA_PLUGIN_NOT_FOUND: An appropriate interpreter plugin for the + * autodetected game file type could not be found. + * @CHIMARA_PLUGIN_ALREADY_RUNNING: A plugin was opened while there was already + * another plugin running in the widget. * * Error codes returned by #ChimaraGlk widgets and subclasses. - * - * - * CHIMARA_LOAD_MODULE_ERROR - * There was an error opening the plugin containing the Glk - * program. The error message from g_module_error() is appended to the GError message. - * - * - * CHIMARA_NO_GLK_MAIN - * The plugin containing the Glk program did not export a - * glk_main() function. - * - * - * CHIMARA_PLUGIN_NOT_FOUND - * An appropriate interpreter plugin for the autodetected - * game file type could not be found. - * - * - * CHIMARA_PLUGIN_ALREADY_RUNNING - * A plugin was opened while there was already another plugin - * running in the widget. - * - * */ typedef enum _ChimaraError { CHIMARA_LOAD_MODULE_ERROR, @@ -97,7 +83,7 @@ gboolean chimara_glk_run(ChimaraGlk *glk, const gchar *plugin, int argc, char *a void chimara_glk_stop(ChimaraGlk *glk); void chimara_glk_wait(ChimaraGlk *glk); gboolean chimara_glk_get_running(ChimaraGlk *glk); -void chimara_glk_feed_char_input(ChimaraGlk *glk, guint32 keycode); +void chimara_glk_feed_char_input(ChimaraGlk *glk, guint32 keyval); void chimara_glk_feed_line_input(ChimaraGlk *glk, const gchar *text); G_END_DECLS diff --git a/libchimara/chimara-if.h b/libchimara/chimara-if.h index 89ea5c8..deda647 100644 --- a/libchimara/chimara-if.h +++ b/libchimara/chimara-if.h @@ -15,38 +15,68 @@ G_BEGIN_DECLS /** * ChimaraIFFormat: - * + * @CHIMARA_IF_FORMAT_Z5: Z-code version 5 + * @CHIMARA_IF_FORMAT_Z6: Z-code version 6 + * @CHIMARA_IF_FORMAT_Z8: Z-code version 8 + * @CHIMARA_IF_FORMAT_Z_BLORB: Blorbed Z-code + * @CHIMARA_IF_FORMAT_GLULX: Glulx + * @CHIMARA_IF_FORMAT_GLULX_BLORB: Blorbed Glulx + * * Constants representing all game formats supported by the Chimara system. */ typedef enum _ChimaraIFFormat { + /*< private >*/ CHIMARA_IF_FORMAT_NONE = -1, + /*< public >*/ CHIMARA_IF_FORMAT_Z5, CHIMARA_IF_FORMAT_Z6, CHIMARA_IF_FORMAT_Z8, CHIMARA_IF_FORMAT_Z_BLORB, CHIMARA_IF_FORMAT_GLULX, CHIMARA_IF_FORMAT_GLULX_BLORB, + /*< private >*/ CHIMARA_IF_NUM_FORMATS } ChimaraIFFormat; /** * ChimaraIFInterpreter: + * @CHIMARA_IF_INTERPRETER_FROTZ: Frotz + * @CHIMARA_IF_INTERPRETER_NITFOL: Nitfol + * @CHIMARA_IF_INTERPRETER_GLULXE: Glulxe + * @CHIMARA_IF_INTERPRETER_GIT: Git * * Constants representing the available interpreter plugins. */ typedef enum _ChimaraIFInterpreter { + /*< private >*/ CHIMARA_IF_INTERPRETER_NONE = -1, + /*< public >*/ CHIMARA_IF_INTERPRETER_FROTZ, CHIMARA_IF_INTERPRETER_NITFOL, CHIMARA_IF_INTERPRETER_GLULXE, CHIMARA_IF_INTERPRETER_GIT, + /*< private >*/ CHIMARA_IF_NUM_INTERPRETERS } ChimaraIFInterpreter; /** * ChimaraIFZmachineVersion: + * @CHIMARA_IF_ZMACHINE_DEFAULT: Use the interpreter's default interpreter + * number. + * @CHIMARA_IF_ZMACHINE_DECSYSTEM_20: DEC System 20 + * @CHIMARA_IF_ZMACHINE_APPLE_IIE: Apple IIe + * @CHIMARA_IF_ZMACHINE_MACINTOSH: Apple Macintosh + * @CHIMARA_IF_ZMACHINE_AMIGA: Commodore Amiga + * @CHIMARA_IF_ZMACHINE_ATARI_ST: Atari ST + * @CHIMARA_IF_ZMACHINE_IBM_PC: IBM PC + * @CHIMARA_IF_ZMACHINE_COMMODORE_128: Commodore 128 + * @CHIMARA_IF_ZMACHINE_COMMODORE_64: Commodore 64 + * @CHIMARA_IF_ZMACHINE_APPLE_IIC: Apple IIc + * @CHIMARA_IF_ZMACHINE_APPLE_IIGS: Apple IIgs + * @CHIMARA_IF_ZMACHINE_TANDY_COLOR: Tandy Color Computer * - * Allowed values for the #ChimaraIF:interpreter-number property. + * Allowed values for the #ChimaraIF:interpreter-number property. All trademarks + * are the property of their respective owners. */ typedef enum _ChimaraIFZmachineVersion { CHIMARA_IF_ZMACHINE_DEFAULT = 0, @@ -61,6 +91,7 @@ typedef enum _ChimaraIFZmachineVersion { CHIMARA_IF_ZMACHINE_APPLE_IIC, CHIMARA_IF_ZMACHINE_APPLE_IIGS, CHIMARA_IF_ZMACHINE_TANDY_COLOR, + /*< private >*/ CHIMARA_IF_ZMACHINE_MAXVAL = CHIMARA_IF_ZMACHINE_TANDY_COLOR } ChimaraIFZmachineVersion; diff --git a/libchimara/dispatch.c b/libchimara/dispatch.c index 51c89f3..f154727 100644 --- a/libchimara/dispatch.c +++ b/libchimara/dispatch.c @@ -27,15 +27,15 @@ extern GPrivate *glk_data_key; * actually executing VM code.) You pass in two function pointers, matching the * following prototypes: * |[ - * #gidispatch_rock_t my_vm_reg_object(void *obj, #glui32 objclass); - * void my_vm_unreg_object(void *obj, #glui32 objclass, #gidispatch_rock_t objrock); + * gidispatch_rock_t my_vm_reg_object(void *obj, glui32 objclass); + * void my_vm_unreg_object(void *obj, glui32 objclass, gidispatch_rock_t objrock); * ]| * - * Whenever the Glk library creates an object, it will call my_vm_reg_object(). - * It will pass the object pointer and the class number (from 0 to - * N - 1N - - * 1, where N is the value returned by - * gidispatch_count_classes().) + * Whenever the Glk library creates an object, it will call + * my_vm_reg_object(). It will pass the object + * pointer and the class number (from 0 to N - + * 1N - 1, where N is the value + * returned by gidispatch_count_classes().) * * You can return any value in the #gidispatch_rock_t object; the library will * stash this away inside the object. @@ -46,8 +46,8 @@ extern GPrivate *glk_data_key; * * * Whenever the Glk library destroys an object, it will call - * my_vm_unreg_object(). It passes you the object pointer, class number, and the - * object rock. + * my_vm_unreg_object(). It passes you the object + * pointer, class number, and the object rock. * * One significant detail: It is possible that some Glk objects will already * exist when your glk_main() function is called. @@ -58,8 +58,8 @@ extern GPrivate *glk_data_key; * * * So when you call gidispatch_set_object_registry(), it may immediately call - * your my_vm_reg_object() callback, notifying you of the existing objects. You - * must be prepared for this possibility. + * your my_vm_reg_object() callback, notifying + * you of the existing objects. You must be prepared for this possibility. * * * If you are keeping hash tables, for example, create them before you call @@ -144,17 +144,17 @@ gidispatch_get_objrock(void *obj, glui32 objclass) * * Again, you pass in two function pointers: * |[ - * #gidispatch_rock_t my_vm_reg_array(void *array, #glui32 len, char *typecode); - * void my_vm_unreg_array(void *array, #glui32 len, char *typecode, #gidispatch_rock_t objrock); + * gidispatch_rock_t my_vm_reg_array(void *array, glui32 len, char *typecode); + * void my_vm_unreg_array(void *array, glui32 len, char *typecode, gidispatch_rock_t objrock); * ]| * - * Whenever a Glk function retains an array, it will call my_vm_reg_array(). - * This occurs only if you pass an array to an argument with the - * "#!" prefix. + * Whenever a Glk function retains an array, it will call + * my_vm_reg_array(). This occurs only if you + * pass an array to an argument with the "#!" prefix. * * - * But not in every such case. Wait for the my_vm_reg_array() call to confirm - * it. + * But not in every such case. Wait for the + * my_vm_reg_array() call to confirm it. * * * The library passes the array and its length, exactly as you put them in the @@ -172,9 +172,9 @@ gidispatch_get_objrock(void *obj, glui32 objclass) * stash this away with the array. * * When a Glk function releases a retained array, it will call - * my_vm_unreg_array(). It passes back the same @array, @len, and @typecode - * parameters, as well as the #gidispatch_rock_t you returned from - * my_vm_reg_array(). + * my_vm_unreg_array(). It passes back the same + * @array, @len, and @typecode parameters, as well as the #gidispatch_rock_t you + * returned from my_vm_reg_array(). * * With these callbacks, you can maintain a collection of retained arrays. You * can use this to copy data from C arrays to your own data structures, or keep diff --git a/libchimara/doc.c b/libchimara/doc.c index cb20d6e..2e61ee4 100644 --- a/libchimara/doc.c +++ b/libchimara/doc.c @@ -157,7 +157,7 @@ * This is how you deal with opaque objects from a C program. If you are using * Glk through a virtual machine, matters will probably be different. Opaque * objects may be represented as integers, or as VM objects of some sort. - * + * * * Rocks * @@ -177,7 +177,7 @@ * For each class of opaque objects, there is an iterate function, which you can * use to obtain a list of all existing objects of that class. It takes the form * |[ - * CLASSid_t glk_CLASS_iterate(CLASSid_t obj, #glui32 *rockptr); + * CLASSid_t glk_CLASS_iterate(CLASSid_t obj, glui32 *rockptr); * ]| * ...where CLASS represents one of the * opaque object classes. @@ -203,10 +203,10 @@ * * You usually use this as follows: * |[ - * obj = glk_CLASS_iterate(NULL, NULL); + * obj = glk_CLASS_iterate(NULL, NULL); * while (obj) { * /* ...do something with obj... */ - * obj = glk_CLASS_iterate(obj, NULL); + * obj = glk_CLASS_iterate(obj, NULL); * } * ]| * @@ -1157,12 +1157,13 @@ * GlkTerm. * * When you compile a Glk program, you may define a function called - * glkunix_startup_code(), and an array glkunix_arguments[]. These - * set up various Unix-specific options used by the Glk library. There is a - * sample glkstart.c file included in this - * package; you should modify it to your needs. + * glkunix_startup_code(), and an array + * glkunix_arguments[]. These set up various Unix-specific options + * used by the Glk library. There is a sample + * glkstart.c file included in this package; + * you should modify it to your needs. * - * |[ extern #glkunix_argumentlist_t glkunix_arguments[]; ]| + * |[ extern glkunix_argumentlist_t glkunix_arguments[]; ]| * * The glkunix_arguments[] array is a list of command-line * arguments that your program can accept. The library will sort these out of @@ -1267,8 +1268,8 @@ * For an example of the gestalt mechanism, consider the selector * %gestalt_Version. If you do * |[ - * #glui32 res; - * res = #glk_gestalt(#gestalt_Version, 0); + * glui32 res; + * res = glk_gestalt(gestalt_Version, 0); * ]| * res will be set to a 32-bit number which encodes the version of * the Glk spec which the library implements. The upper 16 bits stores the major @@ -1283,8 +1284,8 @@ * 0x00000700. * * |[ - * #glui32 res; - * res = #glk_gestalt_ext(#gestalt_Version, 0, NULL, 0); + * glui32 res; + * res = glk_gestalt_ext(gestalt_Version, 0, NULL, 0); * ]| * does exactly the same thing. Note that, in either case, the second argument * is not used; so you should always pass 0 to avoid future surprises. @@ -1296,8 +1297,8 @@ * If you set ch to a character code, or a special code (from * 0xFFFFFFFF down), and call * |[ - * #glui32 res; - * res = #glk_gestalt(#gestalt_CharInput, ch); + * glui32 res; + * res = glk_gestalt(gestalt_CharInput, ch); * ]| * then res will be %TRUE (1) if that character can be typed by * the player in character input, and %FALSE (0) if not. See ch to a character code, and call * |[ - * #glui32 res; - * res = #glk_gestalt(#gestalt_LineInput, ch); + * glui32 res; + * res = glk_gestalt(gestalt_LineInput, ch); * ]| * then res will be %TRUE (1) if that character can be typed by the * player in line input, and %FALSE (0) if not. Note that if ch is @@ -1324,8 +1325,8 @@ * * If you set ch to a character code (Latin-1 or higher), and call * |[ - * #glui32 res, len; - * res = #glk_gestalt_ext(#gestalt_CharOutput, ch, &len, 1); + * glui32 res, len; + * res = glk_gestalt_ext(gestalt_CharOutput, ch, &len, 1); * ]| * then res will be one of %gestalt_CharOutput_CannotPrint, * %gestalt_CharOutput_ExactPrint, or %gestalt_CharOutput_ApproxPrint (see @@ -1353,11 +1354,11 @@ * Make sure you do not get confused by signed byte values. If you set a * char variable ch to 0xFE, the * small-thorn character (þ), and then call - * |[ res = #glk_gestalt(#gestalt_CharOutput, ch); ]| + * |[ res = glk_gestalt(gestalt_CharOutput, ch); ]| * then (by the definition of C/C++) ch will be sign-extended to * 0xFFFFFFFE, which is not a legitimate character, even in Unicode. You * should write - * |[ res = #glk_gestalt(#gestalt_CharOutput, (unsigned char)ch); ]| + * |[ res = glk_gestalt(gestalt_CharOutput, (unsigned char)ch); ]| * instead. * * @@ -1415,7 +1416,7 @@ * gestalt_Timer: * * You can test whether the library supports timer events: - * |[ res = #glk_gestalt(#gestalt_Timer, 0); ]| + * |[ res = glk_gestalt(gestalt_Timer, 0); ]| * This returns 1 if timer events are supported, and 0 if they are not. */ @@ -1425,8 +1426,8 @@ * Before calling Glk graphics functions, you should use the following gestalt * selector: * |[ - * glui32 res; - * res = glk_gestalt(gestalt_Graphics, 0); + * glui32 res; + * res = glk_gestalt(gestalt_Graphics, 0); * ]| * This returns 1 if the overall suite of graphics functions is available. This * includes glk_image_draw(), glk_image_draw_scaled(), glk_image_get_info(), @@ -1453,8 +1454,8 @@ * * You can test whether the library supports hyperlinks: * |[ - * #glui32 res; - * res = #glk_gestalt(#gestalt_Hyperlinks, 0); + * glui32 res; + * res = glk_gestalt(gestalt_Hyperlinks, 0); * ]| * This returns 1 if the overall suite of hyperlinks functions is available. * This includes glk_set_hyperlink(), glk_set_hyperlink_stream(), @@ -1469,7 +1470,7 @@ * * You can test whether hyperlinks are supported with the * %gestalt_HyperlinkInput selector: - * |[ res = #glk_gestalt(#gestalt_HyperlinkInput, windowtype); ]| + * |[ res = glk_gestalt(gestalt_HyperlinkInput, windowtype); ]| * This will return %TRUE (1) if windows of the given type support hyperlinks. * If this returns %FALSE (0), it is still legal to call glk_set_hyperlink() and * glk_request_hyperlink_event(), but they will have no effect, and you will @@ -1497,7 +1498,7 @@ * the following gestalt selector: * |[ * glui32 res; - * res = #glk_gestalt(#gestalt_Unicode, 0); + * res = glk_gestalt(gestalt_Unicode, 0); * ]| * * This returns 1 if the Unicode functions are available. If it returns 0, you @@ -1671,7 +1672,7 @@ * events, this is platform-dependent. See %evtype_Arrange. * * For more about redraw events and how they affect graphics windows, see Graphics Windows. + * linkend="wintype-Graphics">Graphics Windows. */ /** @@ -1865,8 +1866,8 @@ * This value is equal to the number of special keycodes. The last keycode is * always * - * (0x100000000 - keycode_MAXVAL) - * (0x100000000 - keycode_MAXVAL) + * (0x100000000 - keycode_MAXVAL) + * (0x100000000 - keycode_MAXVAL) * * . */ @@ -2687,69 +2688,70 @@ * For example, consider a hypothetical function, with selector * 0xABCD: * |[ - * void glk_glomp(#glui32 num, #winid_t win, #glui32 *numref, #strid_t *strref); + * void glk_glomp(glui32 num, winid_t win, glui32 *numref, strid_t *strref); * ]| * ...and the calls: * |[ - * #glui32 value; - * #winid_t mainwin; - * #strid_t gamefile; + * glui32 value; + * winid_t mainwin; + * strid_t gamefile; * glk_glomp(5, mainwin, &value, &gamefile); * ]| * * To perform this through gidispatch_call(), you would do the following: * |[ - * #gluniversal_t arglist[6]; + * gluniversal_t arglist[6]; * arglist[0].uint = 5; * arglist[1].opaqueref = mainwin; * arglist[2].ptrflag = TRUE; * arglist[3].uint = value; * arglist[4].ptrflag = TRUE; * arglist[5].opaqueref = gamefile; - * #gidispatch_call(0xABCD, 6, arglist); + * gidispatch_call(0xABCD, 6, arglist); * value = arglist[3].uint; * gamefile = arglist[5].opaqueref; * ]| * * Note that you copy the value of the reference arguments into and out of - * @arglist. Of course, it may be that glk_glomp() only uses these as pass-out + * @arglist. Of course, it may be that + * glk_glomp() only uses these as pass-out * references or pass-in references; if so, you could skip copying in or out. * * For further examples: * |[ * glk_glomp(7, mainwin, NULL, NULL); * ...or... - * #gluniversal_t arglist[4]; + * gluniversal_t arglist[4]; * arglist[0].uint = 7; * arglist[1].opaqueref = mainwin; * arglist[2].ptrflag = FALSE; * arglist[3].ptrflag = FALSE; - * #gidispatch_call(0xABCD, 4, arglist); + * gidispatch_call(0xABCD, 4, arglist); * ]| * * |[ * glk_glomp(13, NULL, NULL, &gamefile); * ...or... - * #gluniversal_t arglist[5]; + * gluniversal_t arglist[5]; * arglist[0].uint = 13; * arglist[1].opaqueref = NULL; * arglist[2].ptrflag = FALSE; * arglist[3].ptrflag = TRUE; * arglist[4].opaqueref = gamefile; - * #gidispatch_call(0xABCD, 5, arglist); + * gidispatch_call(0xABCD, 5, arglist); * gamefile = arglist[4].opaqueref; * ]| * * |[ * glk_glomp(17, NULL, &value, NULL); * ...or... - * #gluniversal_t arglist[5]; + * gluniversal_t arglist[5]; * arglist[0].uint = 17; * arglist[1].opaqueref = NULL; * arglist[2].ptrflag = TRUE; * arglist[3].uint = value; * arglist[4].ptrflag = FALSE; - * #gidispatch_call(0xABCD, 5, arglist); + * gidispatch_call(0xABCD, 5, arglist); * value = arglist[3].uint; * ]| * @@ -2765,10 +2767,10 @@ * * For example, the function glk_select() can be invoked as follows: * |[ - * #event_t ev; - * #gluniversal_t arglist[5]; + * event_t ev; + * gluniversal_t arglist[5]; * arglist[0].ptrflag = TRUE; - * #gidispatch_call(0x00C0, 5, arglist); + * gidispatch_call(0x00C0, 5, arglist); * ev.type = arglist[1].uint; * ev.win = arglist[2].opaqueref; * ev.val1 = arglist[3].uint; @@ -2796,15 +2798,15 @@ * * For example, the function glk_put_buffer() can be invoked as follows: * |[ - * #char buf[64]; - * #glui32 len = 64; - * #glk_put_buffer(buf, len); + * char buf[64]; + * glui32 len = 64; + * glk_put_buffer(buf, len); * ...or... - * #gluniversal_t arglist[3]; + * gluniversal_t arglist[3]; * arglist[0].ptrflag = TRUE; * arglist[1].array = buf; * arglist[2].uint = len; - * #gidispatch_call(0x0084, 3, arglist); + * gidispatch_call(0x0084, 3, arglist); * ]| * * Since you are passing a C char array to gidispatch_call(), the contents will @@ -2826,14 +2828,14 @@ * * For example, the function glk_window_get_rock() can be invoked as follows: * |[ - * #glui32 rock; - * #winid_t win; - * rock = #glk_window_get_rock(win); + * glui32 rock; + * winid_t win; + * rock = glk_window_get_rock(win); * ...or... - * #gluniversal_t arglist[3]; + * gluniversal_t arglist[3]; * arglist[0].opaqueref = win; * arglist[1].ptrflag = TRUE; - * #gidispatch_call(0x0021, 3, arglist); + * gidispatch_call(0x0021, 3, arglist); * rock = arglist[2].uint; * ]| * @@ -2847,7 +2849,9 @@ * @uch: Stores an #unsigned #char. * @sch: Stores a #signed #char. * @ch: Stores a #char with the default signedness. - * @charstr: Stores a %NULL-terminated string. + * @charstr: Stores a null-terminated string. + * @unicharstr: Stores a zero-terminated string of #glui32 values representing + * Unicode characters. * @array: Stores a pointer to an array, and should be followed by another * #gluniversal_t with the array length stored in the @uint member. * @ptrflag: If %FALSE, represents an opaque reference or array that is %NULL, @@ -2865,11 +2869,11 @@ * This returns a string which encodes the proper argument list for the given * function. If there is no such function in the library, this returns %NULL. * - * The prototype string for the glk_glomp() function described above would be: - * "4IuQa&Iu&Qb:". The "4" is the number of - * arguments (including the return value, if there is one, which in this case - * there isn't.) "Iu" denotes an unsigned integer; - * "Qa" is an opaque object of class 0 (window). + * The prototype string for the glk_glomp() + * function described above would be: "4IuQa&Iu&Qb:". The + * "4" is the number of arguments (including the return value, if + * there is one, which in this case there isn't.) "Iu" denotes an + * unsigned integer; "Qa" is an opaque object of class 0 (window). * "&Iu" is a reference to an unsigned * integer, and "&Qb" is a reference to a stream. The colon at * the end terminates the argument list; the return value would follow it, if @@ -2877,8 +2881,9 @@ * * Note that the initial number ("4" in this case) is the number of * logical arguments, not the number of #gluniversal_t objects which will be - * passed to gidispatch_call(). The glk_glomp() call uses anywhere from four to - * six #gluniversal_t objects, as demonstrated above. + * passed to gidispatch_call(). The glk_glomp() + * call uses anywhere from four to six #gluniversal_t objects, as demonstrated + * above. * * The basic type codes: * @@ -3183,6 +3188,12 @@ /** * giblorb_result_t: + * @chunknum: The chunk number (for use in giblorb_unload_chunk(), etc.) + * @data: A union containing a pointer to the data @ptr (if you used + * %giblorb_method_Memory) and the position in the file @startpos (if you used + * %giblorb_method_FilePos) + * @length: The length of the data + * @chunktype: The type of the chunk. * * Holds information about a chunk loaded from a Blorb file, and the method of * accessing the chunk data. See giblorb_load_chunk_by_type() and @@ -3334,11 +3345,11 @@ /** * glkunix_argumentlist_t: - * - * In each entry, name is the option as it would appear on the command line - * (including the leading dash, if any.) The desc is a description of the - * argument; this is used when the library is printing a list of options. And - * argtype is one of the following constants: + * @name: the option as it would appear on the command line (including the + * leading dash, if any.) + * @desc: a description of the argument; this is used when the library is + * printing a list of options. + * @argtype: one of the glkunix_arg_ constants. * * * @@ -3376,21 +3387,21 @@ * If you don't care about command-line arguments, you must still define an * empty arguments list, as follows: * |[ - * #glkunix_argumentlist_t glkunix_arguments[] = { - * { NULL, #glkunix_arg_End, NULL } + * glkunix_argumentlist_t glkunix_arguments[] = { + * { NULL, glkunix_arg_End, NULL } * }; * ]| * * Here is a more complete sample list: * |[ - * #glkunix_argumentlist_t glkunix_arguments[] = { - * { "", #glkunix_arg_ValueFollows, "filename: The game file to load." }, - * { "-hum", #glkunix_arg_ValueFollows, "-hum NUM: Hum some NUM." }, - * { "-bom", #glkunix_arg_ValueCanFollow, "-bom [ NUM ]: Do a bom (on - * the NUM, if given)." }, - * { "-goo", #glkunix_arg_NoValue, "-goo: Find goo." }, - * { "-wob", #glkunix_arg_NumberValue, "-wob NUM: Wob NUM times." }, - * { NULL, #glkunix_arg_End, NULL } + * glkunix_argumentlist_t glkunix_arguments[] = { + * { "", glkunix_arg_ValueFollows, "filename: The game file to load." }, + * { "-hum", glkunix_arg_ValueFollows, "-hum NUM: Hum some NUM." }, + * { "-bom", glkunix_arg_ValueCanFollow, "-bom [ NUM ]: Do a bom (on + * the NUM, if given)." }, + * { "-goo", glkunix_arg_NoValue, "-goo: Find goo." }, + * { "-wob", glkunix_arg_NumberValue, "-wob NUM: Wob NUM times." }, + * { NULL, glkunix_arg_End, NULL } * }; * ]| * This would match the arguments thingfile -goo -wob8 -bom -hum @@ -3399,7 +3410,7 @@ * After the library parses the command line, it does various occult rituals of * initialization, and then calls glkunix_startup_code(). * - * |[ int glkunix_startup_code(#glkunix_startup_t *data); ]| + * |[ int glkunix_startup_code(glkunix_startup_t *data); ]| * * This should return %TRUE if everything initializes properly. If it returns * %FALSE, the library will shut down without ever calling your glk_main() @@ -3408,6 +3419,8 @@ /** * glkunix_startup_t: + * @argc: The number of arguments in @argv. + * @argv: Strings representing command line arguments. * * The fields are a standard Unix (argc, argv) list, which contain * the arguments you requested from the command line. In deference to custom, diff --git a/libchimara/fileref.c b/libchimara/fileref.c index d0cee08..a3042ed 100644 --- a/libchimara/fileref.c +++ b/libchimara/fileref.c @@ -164,7 +164,7 @@ glk_fileref_create_temp(glui32 usage, glui32 rock) * Chimara * * Chimara uses a GtkFileChooserDialog. The default + * linkend="GtkFileChooserDialog">GtkFileChooserDialog. The default * starting location for the dialog may be set with glkunix_set_base_file(). * * diff --git a/libchimara/garglk.c b/libchimara/garglk.c index 5e80168..3631d67 100644 --- a/libchimara/garglk.c +++ b/libchimara/garglk.c @@ -4,7 +4,7 @@ extern GPrivate *glk_data_key; -void +static void apply_reverse_color(GtkTextTag *tag, gpointer data) { g_object_set_data( G_OBJECT(tag), "reverse_color", data ); diff --git a/libchimara/glk.c b/libchimara/glk.c index 58b9c00..81d3603 100644 --- a/libchimara/glk.c +++ b/libchimara/glk.c @@ -122,8 +122,8 @@ glk_exit(void) * loop, this is critical. In a C program, you can often eyeball it. * * But the next version of model.c will have a - * glk_tick() in the ornate printing loop of verb_yada(). - * Just to make the point. + * glk_tick() in the ornate printing loop of + * verb_yada(). Just to make the point. * * */ diff --git a/libchimara/glkunix.c b/libchimara/glkunix.c index 704ac0c..13b44ec 100644 --- a/libchimara/glkunix.c +++ b/libchimara/glkunix.c @@ -12,7 +12,7 @@ extern GPrivate *glk_data_key; /** * glkunix_stream_open_pathname: * @pathname: A path to a file, in the system filename encoding. - * @usage: Bitfield with one or more of the fileusage_ constants. + * @textmode: Bitfield with one or more of the fileusage_ constants. * @rock: The new stream's rock value. * * Opens an arbitrary file, in read-only mode. Note that this function is @@ -23,7 +23,7 @@ extern GPrivate *glk_data_key; * Returns: A new stream, or %NULL if the file operation failed. */ strid_t -glkunix_stream_open_pathname(char *pathname, glui32 usage, glui32 rock) +glkunix_stream_open_pathname(char *pathname, glui32 textmode, glui32 rock) { ChimaraGlkPrivate *glk_data = g_private_get(glk_data_key); diff --git a/libchimara/graphics.c b/libchimara/graphics.c index 5735bcb..abcab4a 100644 --- a/libchimara/graphics.c +++ b/libchimara/graphics.c @@ -415,7 +415,7 @@ draw_image_common(winid_t win, GdkPixbuf *pixbuf, glsi32 val1, glsi32 val2) * * This function may only be used with graphics windows. To set background * colors in a text window, use text styles with color hints; see Styles. + * linkend="chimara-Styles">Styles. * */ void diff --git a/libchimara/stream.c b/libchimara/stream.c index b0e97f9..3c15127 100644 --- a/libchimara/stream.c +++ b/libchimara/stream.c @@ -192,7 +192,7 @@ glk_put_char_uni(glui32 ch) * equivalent to * |[ * for (ptr = s; *ptr; ptr++) - * #glk_put_char(*ptr); + * glk_put_char(*ptr); * ]| * However, it may be more efficient. */ @@ -229,7 +229,7 @@ glk_put_string_uni(glui32 *s) * to: * |[ * for (i = 0; i < len; i++) - * #glk_put_char(buf[i]); + * glk_put_char(buf[i]); * ]| * However, it may be more efficient. */ diff --git a/libchimara/window.c b/libchimara/window.c index 15f8f4b..84b6fd9 100644 --- a/libchimara/window.c +++ b/libchimara/window.c @@ -282,11 +282,11 @@ glk_window_get_root() * * So to create a text buffer window which takes the top 40% of the original * window's space, you would execute - * |[ newwin = #glk_window_open(win, #winmethod_Above | #winmethod_Proportional, 40, #wintype_TextBuffer, 0); ]| + * |[ newwin = glk_window_open(win, winmethod_Above | winmethod_Proportional, 40, wintype_TextBuffer, 0); ]| * * To create a text grid which is always five lines high, at the bottom of the * original window, you would do - * |[ newwin = #glk_window_open(win, #winmethod_Below | #winmethod_Fixed, 5, #wintype_TextGrid, 0); ]| + * |[ newwin = glk_window_open(win, winmethod_Below | winmethod_Fixed, 5, wintype_TextGrid, 0); ]| * * Note that the meaning of the @size argument depends on the @method argument. * If the method is %winmethod_Fixed, it also depends on the @wintype argument. @@ -331,7 +331,8 @@ glk_window_get_root() * O. C gets two rows; A gets the rest. All done. * * Then the user maliciously starts squeezing the window down, in stages: - * + * + * * * * @@ -894,7 +895,8 @@ glk_window_close(winid_t win, stream_result_t *result) * Graphics * * Clears the entire window to its current background color. See Graphics Windows. + * linkend="chimara-The-Types-of-Windows#wintype-Graphics">Graphics + * Windows. * * * @@ -990,7 +992,7 @@ glk_window_clear(winid_t win) * @win: A window, or %NULL. * * Sets the current stream to @win's window stream. It is exactly equivalent to - * |[ #glk_stream_set_current(#glk_window_get_stream(@win)) ]| + * |[ glk_stream_set_current(glk_window_get_stream(win)) ]| * See Streams. * * Chimara @@ -1184,15 +1186,15 @@ glk_window_get_size(winid_t win, glui32 *widthptr, glui32 *heightptr) * Consider the example above, where D has collapsed to zero height. Say D was a * text buffer window. You could make a more useful layout by doing * |[ - * #winid_t o2; - * o2 = #glk_window_get_parent(d); - * glk_window_set_arrangement(o2, #winmethod_Above | #winmethod_Fixed, 3, d); + * winid_t o2; + * o2 = glk_window_get_parent(d); + * glk_window_set_arrangement(o2, winmethod_Above | winmethod_Fixed, 3, d); * ]| * That would set D (the upper child of O2) to be O2's key window, and give it a * fixed size of 3 rows. * * If you later wanted to expand D, you could do - * |[ glk_window_set_arrangement(o2, #winmethod_Above | #winmethod_Fixed, 5, NULL); ]| + * |[ glk_window_set_arrangement(o2, winmethod_Above | winmethod_Fixed, 5, NULL); ]| * That expands D to five rows. Note that, since O2's key window is already set * to D, it is not necessary to provide the @keywin argument; you can pass %NULL * to mean leave the key window unchanged. @@ -1202,18 +1204,18 @@ glk_window_get_size(winid_t win, glui32 *widthptr, glui32 *heightptr) * example, you could change O2's key window to be A, but not B. The key window * also cannot be a pair window itself. * - * |[ glk_window_set_arrangement(o2, #winmethod_Below | #winmethod_Fixed, 3, NULL); ]| + * |[ glk_window_set_arrangement(o2, winmethod_Below | winmethod_Fixed, 3, NULL); ]| * This changes the constraint to be on the lower child of * O2, which is A. The key window is still D; so A would then be three rows high * as measured in D's font, and D would get the rest of O2's space. That may not * be what you want. To set A to be three rows high as measured in A's font, you * would do - * |[ glk_window_set_arrangement(o2, #winmethod_Below | #winmethod_Fixed, 3, a); ]| + * |[ glk_window_set_arrangement(o2, winmethod_Below | winmethod_Fixed, 3, a); ]| * * Or you could change O2 to a proportional split: - * |[ glk_window_set_arrangement(o2, #winmethod_Below | #winmethod_Proportional, 30, NULL); ]| + * |[ glk_window_set_arrangement(o2, winmethod_Below | winmethod_Proportional, 30, NULL); ]| * or - * |[ glk_window_set_arrangement(o2, #winmethod_Above | #winmethod_Proportional, 70, NULL); ]| + * |[ glk_window_set_arrangement(o2, winmethod_Above | winmethod_Proportional, 70, NULL); ]| * These do exactly the same thing, since 30% above is the same as * 70% below. You don't need to specify a key window with a proportional * split, so the @keywin argument is %NULL. (You could actually specify either A -- 2.30.2