Update to Blorb protocol 1.5
[projects/chimara/chimara.git] / libchimara / doc.c
index 3c04ce31abdf6c2ea348ff09ac02446588f4c7fe..c45859f7b5cb7e8535ed8aa3807158cc0d7bdad1 100644 (file)
@@ -7,7 +7,6 @@
 /**
  * SECTION:glk-exiting
  * @short_description: How to terminate a Glk program cleanly
- * @include: libchimara/glk.h
  *
  * A Glk program usually ends when the end of the glk_main() function is 
  * reached. You can also terminate it earlier.
@@ -17,7 +16,6 @@
  * SECTION:glk-interrupt
  * @short_description: Specifying an interrupt handler for cleaning up critical
  * resources
- * @include: libchimara/glk.h
  *
  * Most platforms have some provision for interrupting a program —
  * <keycombo action="simul"><keycap function="command">command</keycap>
@@ -34,7 +32,6 @@
 /**
  * SECTION:glk-tick
  * @short_description: Yielding time to the operating system
- * @include: libchimara/glk.h
  *
  * Many platforms have some annoying thing that has to be done every so often,
  * or the gnurrs come from the voodvork out and eat your computer.
@@ -48,7 +45,6 @@
 /**
  * SECTION:glk-types
  * @short_description: Basic types used in Glk
- * @include: libchimara/glk.h
  *
  * For simplicity, all the arguments used in Glk calls are of a very few types.
  * <variablelist>
@@ -96,7 +92,6 @@
 /**
  * SECTION:glk-opaque-objects
  * @short_description: Complex objects in Glk
- * @include: libchimara/glk.h
  *
  * Glk keeps track of a few classes of special objects. These are opaque to your
  * program; you always refer to them using pointers to opaque C structures.
 /**
  * SECTION:glk-gestalt
  * @short_description: Testing Glk's capabilities
- * @include: libchimara/glk.h
  *
  * The <quote>gestalt</quote> mechanism (cheerfully stolen from the Mac OS) is a
  * system by which the Glk API can be upgraded without making your life
 /**
  * SECTION:glk-character-input
  * @short_description: Waiting for a single keystroke
- * @include: libchimara/glk.h
  *
  * You can request that the player hit a single key. See <link 
  * linkend="chimara-Character-Input-Events">Character Input Events</link>.
 /**
  * SECTION:glk-case
  * @short_description: Changing the case of strings
- * @include: libchimara/glk.h
  *
  * Glk has functions to manipulate the case of both Latin-1 and Unicode strings.
  * One Latin-1 lowercase character corresponds to one uppercase character, and
 /**
  * SECTION:glk-normalize
  * @short_description: Combining characters
- * @include: libchimara/glk.h
  *
  * Comparing Unicode strings is difficult, because there can be several ways to
  * represent a piece of text as a Unicode string. For example, the one-character
 /**
  * SECTION:glk-window-opening
  * @short_description: Creating new windows and closing them
- * @include: libchimara/glk.h
  *
  * You can open a new window using glk_window_open() and close it again using
  * glk_window_close().
 /**
  * SECTION:glk-window-constraints
  * @short_description: Manipulating the size of a window
- * @include: libchimara/glk.h
  *
  * There are library functions to change and to measure the size of a window.
  */
 /**
  * SECTION:glk-window-types
  * @short_description: Blank, pair, text grid, text buffer, and graphics windows
- * @include: libchimara/glk.h
  * 
  * A technical description of all the window types, and exactly how they behave.
  */
 /**
  * SECTION:glk-echo-streams
  * @short_description: Creating a copy of a window's output
- * @include: libchimara/glk.h
  *
  * Every window has an associated window stream; you print to the window by
  * printing to this stream. However, it is possible to attach a second stream to
 /**
  * SECTION:glk-window-other
  * @short_description: Miscellaneous functions for windows
- * @include: libchimara/glk.h
  *
  * This section contains functions for windows that don't fit anywhere else.
  */
 /**
  * SECTION:glk-events
  * @short_description: Waiting for events
- * @include: libchimara/glk.h
  *
  * As described in <link linkend="chimara-Your-Programs-Main-Function">Your
  * Program's Main Function</link>, all player input is handed to your program by
 /**
  * SECTION:glk-character-input-events
  * @short_description: Events representing a single keystroke
- * @include: libchimara/glk.h
  *
  * You can request character input from text buffer and text grid windows. See 
  * %evtype_CharInput. There are separate functions for requesting Latin-1 input
 /**
  * SECTION:glk-line-input-events
  * @short_description: Events representing a line of user input
- * @include: libchimara/glk.h
  *
  * You can request line input from text buffer and text grid windows. See
  * %evtype_LineInput. There are separate functions for requesting Latin-1 input
 /**
  * SECTION:glk-mouse-events
  * @short_description: Events representing a mouse click
- * @include: libchimara/glk.h
  *
  * On some platforms, Glk can recognize when the mouse (or other pointer) is 
  * used to select a spot in a window. You can request mouse input only in text 
 /**
  * SECTION:glk-timer-events
  * @short_description: Events sent at fixed intervals
- * @include: libchimara/glk.h
  *
  * You can request that an event be sent at fixed intervals, regardless of what
  * the player does. Unlike input events, timer events can be tested for with
 /**
  * SECTION:glk-streams
  * @short_description: Input and output abstractions
- * @include: libchimara/glk.h
  *
  * All character output in Glk is done through streams. Every window has an
  * output stream associated with it. You can also write to files on disk; every
  * A stream is opened with a particular file mode, see the 
  * <code>filemode_</code> constants below.
  *
+ * <note><para>
+ *   In the stdio library, using fopen(), %filemode_Write would be mode
+ *   <code>"w"</code>; %filemode_Read would be mode <code>"r"</code>;
+ *   %filemode_ReadWrite would be mode <code>"r+"</code>. Confusingly,
+ *   %filemode_WriteAppend cannot be mode <code>"a"</code>, because the stdio
+ *   spec says that when you open a file with mode <code>"a"</code>, then
+ *   fseek() doesn't work. So we have to use mode <code>"r+"</code> for
+ *   appending. Then we run into the <emphasis>other</emphasis> stdio problem,
+ *   which is that <code>"r+"</code> never creates a new file. So
+ *   %filemode_WriteAppend has to <emphasis>first</emphasis> open the file with
+ *   <code>"a"</code>, close it, reopen with <code>"r+"</code>, and then
+ *   fseek() to the end of the file. For %filemode_ReadWrite, the process is
+ *   the same, except without the fseek() &mdash; we begin at the beginning of
+ *   the file.
+ * </para></note>
+ * <note><para>
+ *   We must also obey an obscure geas of ANSI C <code>"r+"</code> files: you
+ *   can't switch from reading to writing without doing an fseek() in between.
+ *   Switching from writing to reading has the same restriction, except that an
+ *   fflush() also works.
+ * </para></note>
+ *
  * For information on opening streams, see the discussion of each specific type
  * of stream in <link linkend="chimara-The-Types-of-Streams">The Types of
  * Streams</link>. Remember that it is always possible that opening a stream
 /**
  * SECTION:glk-print
  * @short_description: Printing to streams
- * @include: libchimara/glk.h
  *
  * You can print Latin-1 and Unicode characters, null-terminated strings, or
  * buffers to any stream. The characters will be converted into the appropriate
 /**
  * SECTION:glk-read
  * @short_description: Reading from streams
- * @include: libchimara/glk.h
  *
  * You can read Latin-1 or Unicode characters, buffers, or whole lines from any
  * stream. The characters will be converted into the form in which you request
 /**
  * SECTION:glk-closing-streams
  * @short_description: Closing streams and retrieving their character counts
- * @include: libchimara/glk.h
  *
  * When you close a Glk stream, you have the opportunity to examine the
  * character counts &mdash; the number of characters written to or read from the
 /**
  * SECTION:glk-stream-positions
  * @short_description: Moving the read/write mark
- * @include: libchimara/glk.h
  *
  * You can set the position of the read/write mark in a stream.
  *
 /**
  * SECTION:glk-styles
  * @short_description: Changing the appearance of printed text
- * @include: libchimara/glk.h
  *
  * You can send style-changing commands to an output stream. After a style
  * change, new text which is printed to that stream will be given the new style,
 /**
  * SECTION:glk-stylehints
  * @short_description: Setting style hints
- * @include: libchimara/glk.h
  *
  * There are no guarantees of how styles will look, but you can make 
  * suggestions.
 /**
  * SECTION:glk-style-measure
  * @short_description: Finding out how the library displays your style hints
- * @include: libchimara/glk.h
  *
  * You can suggest the appearance of a window's style before the window is
  * created; after the window is created, you can test the style's actual
 
 /**
  * SECTION:glk-stream-types
- * @short_description: Window, memory, and file streams
- * @include: libchimara/glk.h
+ * @short_description: Window, memory, file, and resource streams
  *
  * <refsect2 id="chimara-Window-Streams"><title>Window Streams</title>
  * <para>
  * linkend="chimara-File-References">File References</link>.
  * </para>
  * </refsect2>
+ * <refsect2 id="chimara-Resource-Streams"><title>Resource Streams</title>
+ * <para>
+ * You can open a stream which reads from (but not writes to) a resource file.
+ *
+ * <note><para>
+ *   Typically this is embedded in a Blorb file, as Blorb is the official
+ *   resource-storage format of Glk. A Blorb file can contain images and sounds,
+ *   but it can also contain raw data files, which are accessed by
+ *   glk_stream_open_resource() and glk_stream_open_resource_uni(). A data file
+ *   is identified by number, not by a filename. The Blorb usage field will be
+ *   <code>'Data'</code>. The chunk type will be %giblorb_ID_TEXT for text
+ *   resources, %giblorb_ID_BINA for binary resources.
+ * </para></note>
+ *
+ * <note><para>
+ *   If the running program is not associated with a Blorb file, the library may
+ *   look for data files as actual files instead. These would be named
+ *   <filename>DATA1</filename>, <filename>DATA2</filename>, etc, with a suffix
+ *   distinguishing text and binary files. See <quote>Other Resource
+ *   Arrangements</quote> in the Blorb spec: <ulink
+ *   url="http://eblong.com/zarf/blorb/"></ulink>
+ * </para></note>
+ * </para>
+ * </refsect2>
  */
  
 /**
  * SECTION:glk-stream-other
  * @short_description: Miscellaneous functions for streams
- * @include: libchimara/glk.h
  *
  * This section includes functions for streams that don't fit anywhere else.
  */
 /**
  * SECTION:glk-fileref
  * @short_description: A platform-independent way to refer to disk files
- * @include: libchimara/glk.h
  *
  * You deal with disk files using file references. Each fileref is an opaque C
  * structure pointer; see <link linkend="chimara-Opaque-Objects">Opaque 
 /**
  * SECTION:glk-fileref-types
  * @short_description: Four different ways to create a file reference
- * @include: libchimara/glk.h
  *
  * There are four different functions for creating a fileref, depending on how
  * you wish to specify it. Remember that it is always possible that a fileref
 /**
  * SECTION:glk-fileref-other
  * @short_description: Miscellaneous functions for file references
- * @include: libchimara/glk.h
  *
  * This section includes functions for file references that don't fit anywhere
  * else.
 /**
  * SECTION:glk-image-resources
  * @short_description: Graphics in Glk
- * @include: libchimara/glk.h
  *
  * In accordance with this modern age, Glk provides for a modicum of graphical
  * flair. It does not attempt to be a complete graphical toolkit. Those already
 /**
  * SECTION:glk-graphics-windows
  * @short_description: Drawing graphics in graphics windows
- * @include: libchimara/glk.h
  *
  * A graphics window is a rectangular canvas of pixels, upon which you can draw
  * images. The contents are entirely under your control. You can draw as many
 /**
  * SECTION:glk-graphics-text
  * @short_description: Drawing graphics inside or beside text
- * @include: libchimara/glk.h
  *
  * A text buffer is a linear text stream. You can draw images in-line with this
  * text. If you are familiar with HTML, you already understand this model. You
 /**
  * SECTION:glk-graphics-testing
  * @short_description: Checking whether the library supports graphics
- * @include: libchimara/glk.h
  *
  * Before calling Glk graphics functions, you should use the gestalt selector
  * %gestalt_Graphics. To test for additional capabilities, you can also use the
 /**
  * SECTION:glk-sound-channels
  * @short_description: Creating new sound channels and closing them
- * @include: libchimara/glk.h
  *
  * Sounds in Glk are played through sound channels. Sound channels are another
  * type of opaque object, like windows, streams, and file references.
 /**
  * SECTION:glk-playing-sounds
  * @short_description: Producing noise
- * @include: libchimara/glk.h
  *
  * These functions play the actual sounds through the sound channels.
  */
 /**
  * SECTION:glk-sound-other
  * @short_description: Miscellaneous functions for sound channels
- * @include: libchimara/glk.h
  *
  * This section includes functions for sound channels that don't fit anywhere
  * else.
 /**
  * SECTION:glk-sound-testing
  * @short_description: Checking whether the library supports sound
- * @include: libchimara/glk.h
  *
- * Before calling Glk sound functions, you should use the %gestalt_Sound
- * selector. To test for additional capabilities, you can use the 
- * %gestalt_SoundMusic, %gestalt_SoundVolume, and %gestalt_SoundNotify 
- * selectors.
+ * Before calling Glk sound functions, you should use the %gestalt_Sound2
+ * selector.
+ *
+ * Earlier versions of the Glk spec defined separate selectors for various
+ * optional capabilities. This has proven to be an unnecessarily confusing
+ * strategy, and is no longer used. The %gestalt_Sound, %gestalt_SoundMusic,
+ * %gestalt_SoundVolume, and %gestalt_SoundNotify selectors still exist, but you
+ * should not need to test them; the %gestalt_Sound2 selector covers all of
+ * them.
  */
 
 /**
  * SECTION:glk-creating-hyperlinks
  * @short_description: Printing text as a hyperlink
- * @include: libchimara/glk.h
  *
  * Some games may wish to mark up text in their windows with hyperlinks, which
  * can be selected by the player &mdash; most likely by mouse click. Glk allows
 /**
  * SECTION:glk-accepting-hyperlinks
  * @short_description: Generating and catching hyperlink navigation events
- * @include: libchimara/glk.h
  *
  * When you request a hyperlink event in a window, you will receive a hyperlink
  * event when the player clicks on a hyperlink.
 /**
  * SECTION:glk-hyperlinks-testing
  * @short_description: Checking whether the library supports hyperlinks
- * @include: libchimara/glk.h
  *
  * Before calling Glk hyperlink functions, you should use the gestalt selectors
  * %gestalt_Hyperlinks and %gestalt_HyperlinkInput.
 /**
  * SECTION:glk-clock
  * @short_description: Getting the current time from the system clock
- * @include: libchimara/glk.h
  *
  * You can get the current time, either as a Unix timestamp (seconds since 1970)
  * or as a broken-out structure of time elements (year, month, day, hour,
 /**
  * SECTION:glk-clock-conversions
  * @short_description: Converting from timestamps to date structures and back
- * @include: libchimara/glk.h
  *
+ * This section describes functions for converting timestamps to more
+ * human-readable date structures and back.
  */
 
 /**
  * SECTION:glk-clock-testing
  * @short_description: Checking whether the library supports the clock functions
- * @include: libchimara/glk.h
  *
- * Before calling Glk date and time functions, you should use the following
- * gestalt selector.
+ * Before calling Glk date and time functions, you should use the
+ * %gestalt_DateTime selector.
  */
  
 /**
  * SECTION:dispatch-interrogating
  * @short_description: Finding out what functions the Glk library exports
- * @include: libchimara/glk.h, libchimara/gi_dispa.h
  *
  * These are the ancilliary functions that let you enumerate.
  */
 /**
  * SECTION:dispatch-dispatching
  * @short_description: Dispatching the call to the Glk library
- * @include: libchimara/glk.h, libchimara/gi_dispa.h
  *
  * The function gidispatch_call() invokes a function from the Glk library.
  */
 /**
  * SECTION:dispatch-prototypes
  * @short_description: Querying Glk function prototypes
- * @include: libchimara/glk.h, libchimara/gi_dispa.h
  *
  * There are many possible ways to set up a #gluniversal_t array, and it's
  * illegal to call gidispatch_call() with an array which doesn't match the
 /**
  * SECTION:dispatch-library-functions
  * @short_description: Platform-dependent dispatch layer functions
- * @include: libchimara/glk.h, libchimara/gi_dispa.h
  *
  * Ideally, the three layers &mdash; program, dispatch layer, Glk library
  * &mdash; would be completely modular; each would refer only to the layers
 /** 
  * SECTION:blorb-program
  * @short_description: How to use the Blorb layer in your program
- * @include: libchimara/glk.h, libchimara/gi_blorb.h
  *
  * If you wish your program to load its resources from a Blorb file, you need to
  * find and open that file in your startup code. (See <link 
 /**
  * SECTION:blorb-layer
  * @short_description: The platform-independent functions in the Blorb layer
- * @include: libchimara/glk.h, libchimara/gi_blorb.h
  *
  * These are the functions which are implemented in 
  * <filename>gi_blorb.c</filename>. They will be compiled into the library, but
 /** 
  * SECTION:blorb-errors
  * @short_description: Error codes returned by the Blorb layer functions
- * @include: libchimara/glk.h, libchimara/gi_blorb.h
  *
  * All Blorb layer functions, including giblorb_set_resource_map(), return the
  * following error codes.
 /**
  * SECTION:glkext-startup
  * @short_description: Parsing startup options
- * @include: libchimara/glk.h, libchimara/glkstart.h
  *
  * This section describes an extension to Glk for parsing command-line startup
  * options. It was written by Andrew Plotkin for the Glk libraries CheapGlk and
 /**
  * SECTION:glkext-unix
  * @short_description: Unix-specific functions
- * @include: libchimara/glk.h, libchimara/glkstart.h
  *
  * This section describes an extension to Glk for various Unix functions. It was
  * written by Andrew Plotkin for the Glk libraries CheapGlk and GlkTerm.
 /**
  * SECTION:glkext-garglk
  * @short_description: Gargoyle extensions to Glk
- * @include: libchimara/glk.h, libchimara/garglk.h
  *
  * This section describes various extensions to Glk that were written for the
  * popular interpreter <ulink 
  */
 
 /**
- * GLK_MODULE_SOUND:
+ * GLK_MODULE_SOUND2:
  *
  * If you are writing a C program, there is an additional complication. A 
  * library which does not support sound may not implement the sound functions at
  * even get compile-time errors.
  * 
  * To avoid this, you can perform a preprocessor test for the existence of
- * %GLK_MODULE_SOUND. If this is defined, so are all the functions and constants
+ * %GLK_MODULE_SOUND2. If this is defined, so are all the functions and constants
  * described in this section. If not, not.
- */ 
+ */
+
+/**
+ * GLK_MODULE_SOUND:
+ *
+ * You can perform a preprocessor test for the existence of %GLK_MODULE_SOUND.
+ * If this is defined, so are all the functions and constants described in this
+ * section. If not, not.
+ */
  
 /**
  * GLK_MODULE_HYPERLINKS:
  * functions and data types described in this section.
  */
 
+/**
+ * GLK_MODULE_LINE_ECHO:
+ *
+ * If this preprocessor symbol is defined, so is glk_set_echo_line_event(). If
+ * not, not.
+ */
+
+/**
+ * GLK_MODULE_LINE_TERMINATORS:
+ *
+ * If this preprocessor symbol is defined, so is
+ * glk_set_terminators_line_event(). If not, not.
+ */
+
 /**
  * winid_t:
  *
  *   So the version number 78.2.11 would be encoded as 0x004E020B.
  * </para></note>
  *
- * The current Glk specification version is 0.7.2, so this selector will return
- * 0x00000702.
+ * The current Glk specification version is 0.7.4, so this selector will return
+ * 0x00000704.
  *
  * |[
  * glui32 res;
  * may implement both, neither, or only one.  
  */
 
+/**
+ * gestalt_Sound2:
+ *
+ * You can test whether the library supports sound:
+ * |[
+ * glui32 res;
+ * res = glk_gestalt(gestalt_Sound2, 0);
+ * ]|
+ * This returns 1 if the overall suite of sound functions is available. This
+ * includes all the functions defined in <link
+ * linkend="chimara-glk-spec-sound">this chapter</link>. It also includes the
+ * capabilities described below under %gestalt_SoundMusic, %gestalt_SoundVolume,
+ * and %gestalt_SoundNotify.
+ */
+
 /**
  * gestalt_Sound:
  *
- * You can test whether the library supports sound: 
  * |[
  * glui32 res;
  * res = glk_gestalt(gestalt_Sound, 0);
  * glk_sound_load_hint().
  *
  * If this selector returns 0, you should not try to call these functions. They 
- * may have no effect, or they may cause a run-time error. 
+ * may have no effect, or they may cause a run-time error.
+ *
+ * This selector is guaranteed to return 1 if %gestalt_Sound2 does.
  */
 
 /**
  *
  * You can test whether the library supports setting the volume of sound 
  * channels: 
- * |[
- * glui32 res;
- * res = glk_gestalt(gestalt_SoundVolume, 0);
- * ]|
+ * |[ res = glk_gestalt(gestalt_SoundVolume, 0); ]|
  * This selector returns 1 if the glk_schannel_set_volume() function works. If 
- * it returns zero, glk_schannel_set_volume() has no effect.     
+ * it returns zero, glk_schannel_set_volume() has no effect.
+ *
+ * This selector is guaranteed to return 1 if %gestalt_Sound2 does.
  */
 
 /**
  * gestalt_SoundNotify:
  *
  * You can test whether the library supports sound notification events:
- * |[
- * glui32 res;
- * res = glk_gestalt(gestalt_SoundNotify, 0);
- * ]| 
+ * |[ res = glk_gestalt(gestalt_SoundNotify, 0); ]| 
  * This selector returns 1 if the library supports sound notification events. If
- * it returns zero, you will never get such events. 
+ * it returns zero, you will never get such events.
+ *
+ * This selector is guaranteed to return 1 if %gestalt_Sound2 does.
  */
 
 /**
  *   course, an ugly hack. It is a concession to the current state of the Glk 
  *   libraries, some of which can handle AIFF but not MOD sounds.
  * </para></note>
+ *
+ * This selector is guaranteed to return 1 if %gestalt_Sound2 does.
  */ 
   
 /**
  * ]|
  *
  * This returns 1 if the overall suite of system clock functions, as described
- * in this chapter, is available.
+ * in <link linkend="chimara-The-System-Clock">this chapter</link>, is
+ * available.
  *
  * If this selector returns 0, you should not try to call these functions. They
  * may have no effect, or they may cause a run-time error.
  * </para></note>
  */
 
+/**
+ * gestalt_ResourceStream:
+ *
+ * |[
+ * res = glk_gestalt(gestalt_ResourceStream, 0);
+ * ]|
+ *
+ * This returns 1 if the glk_stream_open_resource() and
+ * glk_stream_open_resource_uni() functions are available. If it returns 0, you
+ * should not call them.
+ */
+
 /**
  * evtype_None:
  *
 /**
  * evtype_SoundNotify:
  *
+ * The completion of a sound being played in a sound channel.
+ *
  * On platforms that support sound, you can request to receive an 
  * %evtype_SoundNotify event when a sound finishes playing. See <link
  * linkend="chimara-Playing-Sounds">Playing Sounds</link>.
  
 /**
  * evtype_Hyperlink:
+ *
+ * The selection of a hyperlink in a window.
  * 
  * On platforms that support hyperlinks, you can request to receive an
  * %evtype_Hyperlink event when the player selects a link. See <link
  * Events</link>.
  */
 
+/**
+ * evtype_VolumeNotify:
+ *
+ * The completion of a gradual volume change in a sound channel.
+ *
+ * On platforms that support sound, you can request to receive an
+ * %evtype_VolumeNotify event when a gradual volume change completes. See <link
+ * linkend="chimara-Playing-Sounds">Playing Sounds</link>.
+ */
+
 /**
  * event_t:
  * @type: the event type
  * When calling glk_window_open() with this @method, it specifies that there
  * should be a visible window border between the new window and its sibling.
  * (This is a hint to the library.)
+ *
+ * <note><title>Chimara</title><para>
+ *   There will only be a visible border if the #ChimaraGlk:spacing property
+ *   is nonzero. Setting #ChimaraGlk:spacing to zero disables all borders on Glk
+ *   windows.
+ * </para></note>
  */
 
 /**
  * linefeed-plus-carriage-return combinations; Latin-1 characters may be
  * converted to native character codes. When reading a file in text mode, native
  * line breaks will be converted back to newline (0x0A) characters, and native
- * character codes may be converted to Latin-1. 
+ * character codes may be converted to Latin-1 or UTF-8
  *
  * <note><para>
  *   Line breaks will always be converted; other conversions are more
  * <warning><para>Margin images are not implemented yet.</para></warning>
  */
 
+/**
+ * glkdate_t:
+ * @year: The full (four-digit) year
+ * @month: The month number, ranging from 1-12, 1 is January
+ * @day: The day of the month, ranging from 1-31
+ * @weekday: The day of the week, ranging from 0-6, 0 is Sunday
+ * @hour: The hour of the day, ranging from 0-23
+ * @minute: The minute of the hour, ranging from 0-59
+ * @second: The second of the minute, ranging from 0-59; may be 60 during a leap
+ * second
+ * @microsec: The fraction of the second in microseconds, ranging from 0-999999
+ *
+ * This structure represents a human-readable date in a specific timezone.
+ */
+
 /**
  * glktimeval_t:
+ * @high_sec: The most significant 32 bits of the timestamp in seconds.
+ * @low_sec: The least significant 32 bits of the timestamp in seconds.
+ * @microsec: The fraction of the timestamp, in microseconds, ranging from
+ * 0-999999.
  *
+ * This structure represents the Unix timestamp, i.e. the number of seconds
+ * since January 1, 1970.
  */
  
 /*---------- TYPES, FUNCTIONS AND CONSTANTS FROM GI_DISPA.H ------------------*/
  *
  * Returns: Number of opaque object classes used by the library.
  */
+
+/**
+ * gidispatch_get_class:
+ * @index: Unique integer index of the class.
+ *
+ * Returns a structure describing an opaque class that the library exports.
+ * @index can range from 0 to <inlineequation><mathphrase>N -
+ * 1</mathphrase><alt>N - 1</alt></inlineequation>, where N is the value
+ * returned by gidispatch_count_classes().
+ *
+ * Returns: A #gidispatch_intconst_t structure describing the class.
+ */
+
 /**
  * gidispatch_count_intconst:
  *
  * Resource usage constant representing an image file.
  */
 
+/**
+ * giblorb_ID_Data:
+ *
+ * Resource usage constant representing a data file.
+ */
+
 /**
  * giblorb_ID_Copyright:
  *
  * Resource usage constant representing any textual annotation that the user or 
  * writing program sees fit to include.
  */ 
+
+/**
+ * giblorb_ID_TEXT:
+ *
+ * Resource usage constant representing a text data file.
+ */
+
+/**
+ * giblorb_ID_BINA:
+ *
+ * Resource usage constant representing a binary data file.
+ */
+
 /**
  * giblorb_map_t:
  *