Add documentation for ansi.stp tapset.

* tapset/ansi.stp: Add documentation for every function.
* doc/SystemTap_Tapset_Reference/tapsets.tmpl: Add chapter on ansi.

2 files changed, 88 insertions, 15 deletions

diff --git a/doc/SystemTap_Tapset_Reference/tapsets.tmpl b/doc/SystemTap_Tapset_Reference/tapsets.tmpl
index ff1d50da..addcf88d 100644
--- a/doc/SystemTap_Tapset_Reference/tapsets.tmpl
+++ b/doc/SystemTap_Tapset_Reference/tapsets.tmpl
@@ -261,4 +261,13 @@
     </para>
 !Itapset/conversions.stp
     </chapter>
+  <chapter id="ansi.stp">
+    <title>Utility functions for using ansi control chars in logs</title>
+    <para>
+      Utility functions for logging using ansi control characters. This
+      lets you manipulate the cursor position and character color output
+      and attributes of log messages.
+    </para>
+!Itapset/ansi.stp
+    </chapter>
 </book>
diff --git a/tapset/ansi.stp b/tapset/ansi.stp
index 0152fb37..ea5376ae 100644
--- a/tapset/ansi.stp
+++ b/tapset/ansi.stp
@@ -9,62 +9,126 @@
 # Reference: http://en.wikipedia.org/wiki/ANSI_escape_code
 #
 
+/**
+ * sfunction ansi_clear_screen - Move cursor to top left and clear screen.
+ *
+ * Description: Sends ansi code for moving cursor to top left and then the
+ * ansi code for clearing the screen from the cursor position to the end.
+ **/
 function ansi_clear_screen() {
 	print("\033[1;1H\033[J")
 }
 
-# Foreground colors | Background colors
-# Black       30    | Black       40
-# Blue        34    | Red         41
-# Green       32    | Green       42
-# Cyan        36    | Yellow      43
-# Red         31    | Blue        44
-# Purple      35    | Magenta     45
-# Brown       33    | Cyan        46
-# Light Gray  37    | White       47
+/**
+ * sfunction ansi_set_color - Set the ansi Select Graphic Rendition mode.
+ * @fg: Foreground color to set.
+ *
+ * Description: Sends ansi code for Select Graphic Rendition mode for the
+ * given forground color. Black (30), Blue (34), Green (32), Cyan (36),
+ * Red (31), Purple (35), Brown (33), Light Gray (37).
+ */
 function ansi_set_color(fg:long) {
 	printf("\033[%dm", fg)
 }
 
+/**
+ * sfunction ansi_set_color2 - Set the ansi Select Graphic Rendition mode.
+ * @fg: Foreground color to set.
+ * @bg: Background color to set.
+ *
+ * Description: Sends ansi code for Select Graphic Rendition mode for the
+ * given forground color, Black (30), Blue (34), Green (32), Cyan (36),
+ * Red (31), Purple (35), Brown (33), Light Gray (37) and the given
+ * background color, Black (40), Red (41), Green (42), Yellow (43),
+ * Blue (44), Magenta (45), Cyan (46), White (47).
+ */
 function ansi_set_color2(fg:long, bg:long) {
 	printf("\033[%d;%dm", bg, fg)
 }
 
-# All attributes off  0
-# Intensity: Bold     1
-# Underline: Single   4
-# Blink: Slow         5
-# Blink: Rapid        6
-# Image: Negative     7
+/**
+ * sfunction ansi_set_color3 - Set the ansi Select Graphic Rendition mode.
+ * @fg: Foreground color to set.
+ * @bg: Background color to set.
+ * @attr: Color attribute to set.
+ *
+ * Description: Sends ansi code for Select Graphic Rendition mode for the
+ * given forground color, Black (30), Blue (34), Green (32), Cyan (36),
+ * Red (31), Purple (35), Brown (33), Light Gray (37), the given
+ * background color, Black (40), Red (41), Green (42), Yellow (43),
+ * Blue (44), Magenta (45), Cyan (46), White (47) and the color attribute
+ * All attributes off (0), Intensity Bold (1), Underline Single (4),
+ * Blink Slow (5), Blink Rapid (6), Image Negative (7).
+ */
 function ansi_set_color3(fg:long, bg:long, attr:long) {
 	attr_str = attr ? sprintf(";%dm", attr) : "m"
 	printf("\033[%d;%d%s", bg, fg, attr_str)
 }
 
+/**
+ * sfunction ansi_reset_color - Resets Select Graphic Rendition mode.
+ *
+ * Description: Sends ansi code to reset foreground, background and color
+ * attribute to default values.
+ */
 function ansi_reset_color() {
 	ansi_set_color3(0, 0, 0)
 }
 
+/**
+ * sfunction ansi_new_line - Move cursor to new line.
+ *
+ * Description: Sends ansi code new line.
+ */
 function ansi_new_line() {
 	printf("\12")
 }
 
+/**
+ * sfunction ansi_cursor_move - Move cursor to new coordinates.
+ * @x: Row to move the cursor to.
+ * @y: Colomn to move the cursor to.
+ *
+ * Description: Sends ansi code for positioning the cursor at row x
+ * and column y. Coordinates start at one, (1,1) is the top-left corner.
+ */
 function ansi_cursor_move(x:long, y:long) {
 	printf("\033[%d;%dH", y, x)
 }
 
+/**
+ * sfunction ansi_cursor_hide - Hides the cursor.
+ *
+ * Description: Sends ansi code for hiding the cursor.
+ */
 function ansi_cursor_hide() {
 	print("\033[>5I")
 }
 
+/**
+ * sfunction ansi_cursor_saves - Saves the cursor position.
+ *
+ * Description: Sends ansi code for saving the current cursor position.
+ */
 function ansi_cursor_save() {
 	print("\033[s")
 }
 
+/**
+ * sfunction ansi_cursor_saves - Restores a previously saved cursor position.
+ *
+ * Description: Sends ansi code for restoring the current cursor position
+ * previously saved with ansi_cursor_save().
+ */
 function ansi_cursor_restore() {
 	print("\033[u")
 }
 
+/**
+ * sfunction ansi_cursor_show - Shows the cursor.
+ *
+ * Description: Sends ansi code for showing the cursor.
+ */
 function ansi_cursor_show() {
 	print("\033[>5h")
 }