Add Doxygen comments to the Turtle graphics library (C and header fil…

…es).

TODO.md

@@ -42,7 +42,7 @@ direct HPGL programs and Turtle programs.
 * Make Turtle library drive the plotter directly, as the HPGL library
 does. This would eliminate the need to redirect the output to the
 plotter (using shell I/O redirection) when plotting Turtle programs.
-* Add Doxygen comments to the library source.
+* Write complete Doxygen comments in the library source.
 
 ## Plotting programs
 * Add new drawings! Especially colouring-in drawings, all-over patterns,

turtle.c

@@ -28,6 +28,17 @@ static double Xpos, Ypos;
 static int Penstate, Pencol;
 static int Main_flags;
 
+
+/**
+ * @brief Initialise the turtle graphics subsystem
+ *
+ * @param dev   Device to use, ::DEV_HPGL, ::DEV_PS, ::DEV_BMC, ::DEV_VGA
+ * @param siz   Paper size, ::SIZ_A1, ::SIZ_A2, ::SIZ_A3, ::SIZ_A4, ::SIZ_A5
+ * @param ori   Drawing orientation (unused), ::ORI_LAND, ::ORI_PORT
+ * @param flags Option flags, ::FLG_NONE, ::FLG_SLOW, ::FLG_BORD
+ *
+ * @return 0 if successful, 1 otherwise
+ */
 int turtle(const int dev, const int siz, const int ori, const int flags)
 {
    Pltdev = dev;
@@ -169,8 +180,9 @@ int turtle(const int dev, const int siz, const int ori, const int flags)
 }
 
 
-/* show --- finish off the plot */
-
+/** 
+ * @brief Finish off the plot
+ */
 void show(void)
 {
    switch (Pltdev) {
@@ -191,8 +203,14 @@ void show(void)
 }
 
 
-/* title --- draw a title on the plot */
-
+/**
+ * @brief Draw a title on the plot
+ *
+ * @param str   String to draw as a title
+ * @param size  Size of text
+ * @param posn  Position of text
+ * @param flags Flags, ::ITALIC
+ */
 void title(const char str[], const double size, const int posn, const int flags)
 {
    int x, y;
@@ -264,8 +282,9 @@ void title(const char str[], const double size, const int posn, const int flags)
 }
 
 
-/* bottom_left --- move the turtle to the bottom left corner */
-
+/**
+ * @brief Move the turtle to the bottom left corner
+ */
 void bottom_left(void)
 {
    Xpos = Minx;
@@ -289,8 +308,11 @@ void bottom_left(void)
 }
 
 
-/* set_heading --- set the turtle heading to an absolute angle */
-
+/**
+ * @brief Set the turtle heading to an absolute angle
+ *
+ * @param deg New heading in degrees
+ */
 void set_heading(const double deg)
 {
    Heading = deg;
@@ -300,8 +322,11 @@ void set_heading(const double deg)
 }
 
 
-/* forward --- move the turtle forward by a given number of millimetres */
-
+/**
+ * @brief Move the turtle forward by a given number of millimetres
+ *
+ * @param mm Number of millimetres to move
+ */
 void forward(const double mm)
 {
    const double len = mm * Scale;
@@ -337,8 +362,11 @@ void forward(const double mm)
 }
 
 
-/* turn --- turn the turtle by a given number of degrees */
-
+/**
+ * @brief Turn the turtle by a given number of degrees
+ *
+ * @param deg Number of degrees to turn
+ */
 void turn(const double deg)
 {
    Heading += deg;
@@ -357,16 +385,22 @@ void turn(const double deg)
 }
 
 
-/* pen --- raise or lower the pen; only draws when pen down */
-
+/**
+ * @brief Raise or lower the pen; only draws when pen down
+ *
+ * @param flag New pen state, ::UP or ::DOWN
+ */
 void pen(const int flag)
 {
    Penstate = flag;
 }
 
 
-/* colour --- set the pen colour */
-
+/**
+ * @brief Set the pen colour
+ *
+ * @param c New pen colour
+ */
 void colour(const int c)
 {
    if (Pencol == c)
@@ -392,8 +426,11 @@ void colour(const int c)
 }
 
 
-/* page_width --- return width of page in millimetres */
-
+/**
+ * @brief Return width of page in millimetres
+ *
+ * @return width of page in millimetres
+ */
 double page_width(void)
 {
    if (Pltdev != DEV_NONE)
@@ -405,8 +442,11 @@ double page_width(void)
 }
 
 
-/* page_height --- return height of page in millimetres */
-
+/**
+ * @brief Return height of page in millimetres
+ *
+ * @return height of page in millimetres
+ */
 double page_height(void)
 {
    if (Pltdev != DEV_NONE)

turtle.h

@@ -1,42 +1,42 @@
 /* turtle --- header file for turtle graphics library       1996-12-15 */
 /* Copyright (c) 1996 John Honniball, Froods Software Development      */
 
-#define DEV_NONE  (0)
-#define DEV_HPGL  (1)
-#define DEV_BMC   (2)
-#define DEV_PS    (3)
-#define DEV_VGA   (4)
-
-#define SIZ_A1    (1)
-#define SIZ_A2    (2)
-#define SIZ_A3    (3)
-#define SIZ_A4    (4)
-#define SIZ_A5    (5)
-
-#define ORI_LAND  (0)
-#define ORI_PORT  (1)
-
-#define FLG_NONE  (0)
-#define FLG_BORD  (1)
-#define FLG_SLOW  (2)
-#define FLG_RELS  (4)
-
-#define ITALIC    (1)
-
-#define UP        (0)
-#define DOWN      (1)
-
-#define TOP       (1)
-#define MID       (2)
-#define BOT       (3)
-#define LEFT      (4)
-#define CENTRE    (8)
-#define RIGHT     (12)
-
-#define BLACK     (1)
-#define RED       (2)
-#define GREEN     (3)
-#define BLUE      (4)
+#define DEV_NONE  (0)   //!< No device selected
+#define DEV_HPGL  (1)   //!< Hewlett-Packard Graphics Language
+#define DEV_BMC   (2)   //!< BMC plotter commands
+#define DEV_PS    (3)   //!< Postscript language
+#define DEV_VGA   (4)   //!< VGA graphics @todo May be obsolete, remove
+
+#define SIZ_A1    (1)   //!< ISO A1 paper size
+#define SIZ_A2    (2)   //!< ISO A2 paper size
+#define SIZ_A3    (3)   //!< ISO A3 paper size
+#define SIZ_A4    (4)   //!< ISO A4 paper size
+#define SIZ_A5    (5)   //!< ISO A5 paper size
+
+#define ORI_LAND  (0)   //!< Drawing orientation landscape @todo Implement this feature
+#define ORI_PORT  (1)   //!< Drawing orientation portrait @todo Implement this feature
+
+#define FLG_NONE  (0)   //!< No flags
+#define FLG_BORD  (1)   //!< Flag to draw a border around the plot
+#define FLG_SLOW  (2)   //!< Flag to slow down the drawing to allow for poor pens
+#define FLG_RELS  (4)   //!< Relative size flag
+
+#define ITALIC    (1)   //!< Use an italic font (or just a slant)
+
+#define UP        (0)   //!< Pen up, turtle moves will not draw anything
+#define DOWN      (1)   //!< Pen down, turtle moves will draw a line
+
+#define TOP       (1)   //!< Position of title text: top of page
+#define MID       (2)   //!< Position of title text: middle of page
+#define BOT       (3)   //!< Position of title text: bottom of page
+#define LEFT      (4)   //!< Position of title text: left of page
+#define CENTRE    (8)   //!< Position of title text: centre of page
+#define RIGHT     (12)  //!< Position of title text: right of page
+
+#define BLACK     (1)   //!< Pen colour black (only truly correct for BMC plotter)
+#define RED       (2)   //!< Pen colour red (only truly correct for BMC plotter)
+#define GREEN     (3)   //!< Pen colour green (only truly correct for BMC plotter)
+#define BLUE      (4)   //!< Pen colour blue (only truly correct for BMC plotter)
 
 int turtle(const int dev, const int siz, const int ori, const int flags);
 void show(void);