From: P. F. Chimento <philip.chimento@gmail.com>
Date: Thu, 14 Apr 2011 21:25:15 +0000 (+0200)
Subject: Misc Garglk extensions documenting
X-Git-Tag: v0.9~111
X-Git-Url: https://git.stderr.nl/gitweb?p=projects%2Fchimara%2Fchimara.git;a=commitdiff_plain;h=eadb51bbb70b0b71a283ed7af7977dc10031f1ff

Misc Garglk extensions documenting
---

diff --git a/libchimara/garglk.c b/libchimara/garglk.c
index 9e503b3..78bdfd5 100644
--- a/libchimara/garglk.c
+++ b/libchimara/garglk.c
@@ -162,7 +162,16 @@ garglk_unput_string_uni(glui32 *str)
 	WARNING(_("Not implemented"));
 }
 
-/* TODO document */
+/**
+ * garglk_set_zcolors_stream:
+ * @str: a stream.
+ * @fg: a 24-bit foreground color.
+ * @bg: a 24-bit background color.
+ *
+ * This function changes the foreground color of @str to @fg and the background
+ * color to @bg. @fg and @bg are encoded the same way as described in
+ * %stylehint_TextColor. See garglk_set_zcolors() for more information.
+ */
 void
 garglk_set_zcolors_stream(strid_t str, glui32 fg, glui32 bg)
 {
@@ -292,16 +301,15 @@ garglk_set_zcolors_stream(strid_t str, glui32 fg, glui32 bg)
 
 /**
  * garglk_set_zcolors:
- * @fg: one of the <code>zcolor_</code> constants.
- * @bg: one of the <code>zcolor_</code> constants.
+ * @fg: a 24-bit foreground color.
+ * @bg: a 24-bit background color.
  *
  * Glk works with styles, not specific colors. This is not quite compatible with
  * the Z-machine, so this Glk extension implements Z-machine style colors.
  *
  * This function changes the foreground color of the current stream to @fg and 
- * the background color to @bg.
- *
- * <warning><para>This function is not currently implemented.</para></warning>
+ * the background color to @bg. @fg and @bg are encoded the same way as
+ * described in %stylehint_TextColor.
  */
 void 
 garglk_set_zcolors(glui32 fg, glui32 bg)
@@ -312,7 +320,15 @@ garglk_set_zcolors(glui32 fg, glui32 bg)
 	garglk_set_zcolors_stream(glk_data->current_stream, fg, bg);
 }
 
-/* TODO document */
+/**
+ * garglk_set_reversevideo_stream:
+ * @str: a stream.
+ * @reverse: nonzero for reverse colors, zero for normal colors.
+ *
+ * If @reverse is not zero, uses the foreground color of @str as its background
+ * and vice versa. If @reverse is zero, changes the colors of @str back to
+ * normal.
+ */
 void
 garglk_set_reversevideo_stream(strid_t str, glui32 reverse)
 {
diff --git a/libchimara/garglk.h b/libchimara/garglk.h
index 7396814..1e55f5b 100644
--- a/libchimara/garglk.h
+++ b/libchimara/garglk.h
@@ -9,8 +9,11 @@
  * macro is defined, then so are all the Gargoyle extensions. If not, not.
  *
  * <note><title>Chimara</title><para>
- *   Currently, in Chimara, the functions are defined, but most of them are
- *   not implemented. That is, you can call them, but they do nothing.
+ *   Currently, in Chimara, the functions are defined, but a few of them
+ *   (garglk_set_line_terminators(),
+ *   garglk_unput_string(), and garglk_unput_string_uni()) are not implemented.
+ *   You can call them, but they will have no effect except to print a warning
+ *   to the console.
  * </para></note>
  */
 #define GARGLK 1