added more minor doxygen comments for fl_draw.H and fl_line_style.cxx

git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6444 ea41ed52-d2ee-0310-a9c1-e6b18d33e121

2 files changed, 47 insertions, 14 deletions

diff --git a/FL/fl_draw.H b/FL/fl_draw.H
index e5133421c..0f89c44de 100644
--- a/FL/fl_draw.H
+++ b/FL/fl_draw.H
@@ -68,19 +68,19 @@ FL_EXPORT void fl_point(int x, int y);
 // line type:
 FL_EXPORT void fl_line_style(int style, int width=0, char* dashes=0);
 enum {
-  FL_SOLID	= 0,
-  FL_DASH	= 1,
-  FL_DOT	= 2,
-  FL_DASHDOT	= 3,
-  FL_DASHDOTDOT	= 4,
-
-  FL_CAP_FLAT	= 0x100,
-  FL_CAP_ROUND	= 0x200,
-  FL_CAP_SQUARE	= 0x300,
-
-  FL_JOIN_MITER	= 0x1000,
-  FL_JOIN_ROUND	= 0x2000,
-  FL_JOIN_BEVEL	= 0x3000
+  FL_SOLID	= 0,		///< line style: <tt>___________</tt>
+  FL_DASH	= 1,		///< line style: <tt>_ _ _ _ _ _</tt>
+  FL_DOT	= 2,		///< line style: <tt>. . . . . .</tt>
+  FL_DASHDOT	= 3,		///< line style: <tt>_ . _ . _ .</tt>
+  FL_DASHDOTDOT	= 4,		///< line style: <tt>_ . . _ . .</tt>
+
+  FL_CAP_FLAT	= 0x100,	///< cap style: end is flat
+  FL_CAP_ROUND	= 0x200,	///< cap style: end is round
+  FL_CAP_SQUARE	= 0x300,	///< cap style: end wraps end point
+
+  FL_JOIN_MITER	= 0x1000,	///< join style: line join extends to a point
+  FL_JOIN_ROUND	= 0x2000,	///< join style: line join is rounded
+  FL_JOIN_BEVEL	= 0x3000	///< join style: line join is tidied
 };
 
 // rectangles tweaked to exactly fill the pixel rectangle:
@@ -187,9 +187,10 @@ FL_EXPORT void fl_frame2(const char* s, int x, int y, int w, int h);
 FL_EXPORT void fl_draw_box(Fl_Boxtype, int x, int y, int w, int h, Fl_Color);
 
 // images:
+/** signature of some image drawing functions passed as parameters */
+typedef void (*Fl_Draw_Image_Cb)(void*,int,int,int,uchar*);
 FL_EXPORT void fl_draw_image(const uchar*, int,int,int,int, int delta=3, int ldelta=0);
 FL_EXPORT void fl_draw_image_mono(const uchar*, int,int,int,int, int delta=1, int ld=0);
-typedef void (*Fl_Draw_Image_Cb)(void*,int,int,int,uchar*);
 FL_EXPORT void fl_draw_image(Fl_Draw_Image_Cb, void*, int,int,int,int, int delta=3);
 FL_EXPORT void fl_draw_image_mono(Fl_Draw_Image_Cb, void*, int,int,int,int, int delta=1);
 FL_EXPORT void fl_rectf(int x, int y, int w, int h, uchar r, uchar g, uchar b);
diff --git a/src/fl_line_style.cxx b/src/fl_line_style.cxx
index 222ba8a68..63cf2da8d 100644
--- a/src/fl_line_style.cxx
+++ b/src/fl_line_style.cxx
@@ -25,6 +25,11 @@
 //     http://www.fltk.org/str.php
 //
 
+/**
+  \file fl_line_style.cxx
+  \brief Line style drawing utility hiding  different platforms.
+*/
+
 #include <FL/Fl.H>
 #include <FL/fl_draw.H>
 #include <FL/x.H>
@@ -45,6 +50,33 @@ void fl_quartz_restore_line_style_() {
 }
 #endif
 
+/**
+  Set how to draw lines (the "pen").
+  If you change this it is your responsibility to set it back to the default
+  using \c fl_line_style(0).
+
+  \param[in] style A bitmask which is a bitwise-OR of a line style, a cap
+             style, and a join style. If you don't specify a dash type you
+	     will get a solid line. If you don't specify a cap or join type
+	     you will get a system-defined default of whatever value is
+	     fastest.
+  \param[in] width The thickness of the lines in pixels. Zero results in the
+             system defined default, which on both X and Windows is somewhat
+	     different and nicer than 1.
+  \param[in] dashes A pointer to an array of dash lengths, measured in pixels.
+             The first location is how long to draw a solid portion, the next
+	     is how long to draw the fap, then the solid, etc. It is terminated
+	     with a zero-length entry. A \c NULL pointer or a zero-length
+	     array results in a solid line. Odd array sizes are not supported
+	     and result in undefined behavior.
+
+  \note      Because of how line styles are implemented on Win32 systems,
+             you \e must set the line style \e after setting the drawing
+	     color. If you set the color after the line style you will lose
+	     the line style settings.
+  \note      The \a dashes array does not work under Windows 95, 98 or Me,
+             since those operating systems do not support complex line styles.
+*/
 void fl_line_style(int style, int width, char* dashes) {
 
 #if defined(USE_X11)