copied more doxygen comments from drawing.dox back to source code

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

6 files changed, 109 insertions, 9 deletions

diff --git a/FL/Enumerations.H b/FL/Enumerations.H
index 24f834f1e..0e7d7b596 100644
--- a/FL/Enumerations.H
+++ b/FL/Enumerations.H
@@ -670,7 +670,7 @@ const Fl_Font FL_BOLD_ITALIC            = 3;	///< add this to helvetica, courier
  */
 typedef int Fl_Fontsize;
 
-extern FL_EXPORT Fl_Fontsize FL_NORMAL_SIZE;
+extern FL_EXPORT Fl_Fontsize FL_NORMAL_SIZE;	///< normal font size
 
 /** \name Colors */
 /*@{*/
diff --git a/FL/fl_draw.H b/FL/fl_draw.H
index 94f5b5668..370f1cb0b 100644
--- a/FL/fl_draw.H
+++ b/FL/fl_draw.H
@@ -84,21 +84,23 @@ enum {
 
 // rectangles tweaked to exactly fill the pixel rectangle:
 FL_EXPORT void fl_rect(int x, int y, int w, int h);
+/** Draw a 1-pixel border \e inside the given bounding box */
 inline void fl_rect(int x, int y, int w, int h, Fl_Color c) {fl_color(c); fl_rect(x,y,w,h);}
 FL_EXPORT void fl_rectf(int x, int y, int w, int h);
+/** Color a rectangle that exactly fills the given bounding box */
 inline void fl_rectf(int x, int y, int w, int h, Fl_Color c) {fl_color(c); fl_rectf(x,y,w,h);}
 
 // line segments:
-FL_EXPORT void fl_line(int,int, int,int);
-FL_EXPORT void fl_line(int,int, int,int, int,int);
+FL_EXPORT void fl_line(int x, int y, int x1, int y1);
+FL_EXPORT void fl_line(int x, int y, int x1, int y1, int x2, int y2);
 
 // closed line segments:
-FL_EXPORT void fl_loop(int,int, int,int, int,int);
-FL_EXPORT void fl_loop(int,int, int,int, int,int, int,int);
+FL_EXPORT void fl_loop(int x, int y, int x1, int y1, int x2, int y2);
+FL_EXPORT void fl_loop(int x, int y, int x1, int y1, int x2, int y2, int x3, int y3);
 
 // filled polygons
-FL_EXPORT void fl_polygon(int,int, int,int, int,int);
-FL_EXPORT void fl_polygon(int,int, int,int, int,int, int,int);
+FL_EXPORT void fl_polygon(int x, int y, int x1, int y1, int x2, int y2);
+FL_EXPORT void fl_polygon(int x, int y, int x1, int y1, int x2, int y2, int x3, int y3);
 
 // draw rectilinear lines, horizontal segment first:
 FL_EXPORT void fl_xyline(int x, int y, int x1);
diff --git a/documentation/osissues.dox b/documentation/osissues.dox
index baf0e437a..5bba13f81 100644
--- a/documentation/osissues.dox
+++ b/documentation/osissues.dox
@@ -640,7 +640,7 @@ version of FLTK:
 	as -O2 and -O3 seem to work OK. More details can be found
 	in STR#1656
 
-\subject osissues_macos The MacOS Interface
+\section osissues_macos The MacOS Interface
 
 FLTK supports MacOS X using the Apple Carbon library. Older
 versions of MacOS are <I>not</I> supported.
diff --git a/src/fl_arc.cxx b/src/fl_arc.cxx
index d4910aa1c..7d3872901 100644
--- a/src/fl_arc.cxx
+++ b/src/fl_arc.cxx
@@ -25,6 +25,11 @@
 //     http://www.fltk.org/str.php
 //
 
+/**
+  \file fl_arc.cxx
+  \brief Utility functions for drawing arcs and circles.
+*/
+
 // Utility for drawing arcs and circles.  They are added to
 // the current fl_begin/fl_vertex/fl_end path.
 // Incremental math implementation:
@@ -38,7 +43,14 @@ static double _fl_hypot(double x, double y) {
   return sqrt(x*x + y*y);
 }
 
-
+/**
+  Add a series of points to the current path on the arc of a circle; you
+  can get elliptical paths by using scale and rotate before calling fl_arc().
+  \param[in] x,y,r center and radius of circular arc
+  \param[in] start,end angles of start and end of arc measured in degrees
+             counter-clockwise from 3 o'clock. If \a end is less than \a start
+	     then it draws the ark in a clockwise direction.
+*/
 void fl_arc(double x, double y, double r, double start, double end) {
 
   // draw start point accurately:
diff --git a/src/fl_arci.cxx b/src/fl_arci.cxx
index 9cc64f6f3..69425554c 100644
--- a/src/fl_arci.cxx
+++ b/src/fl_arci.cxx
@@ -25,6 +25,11 @@
 //     http://www.fltk.org/str.php
 //
 
+/**
+  \file fl_arci.cxx
+  \brief Utility functions for drawing circles using integers
+*/
+
 // "integer" circle drawing functions.  These draw the limited
 // circle types provided by X and NT graphics.  The advantage of
 // these is that small ones draw quite nicely (probably due to stored
@@ -44,6 +49,28 @@
 #  include <config.h>
 #endif
 
+/**
+  Draw ellipse sections using integer coordinates.
+  
+  These functions match the rather limited circle drawing code provided by X
+  and WIN32. The advantage over using fl_arc with floating point coordinates
+  is that they are faster because they often use the hardware, and they draw
+  much nicer small circles, since the small sizes are often hard-coded bitmaps.
+
+  If a complete circle is drawn it will fit inside the passed bounding box.
+  The two angles are measured in degrees counterclockwise from 3'oclock and
+  are the starting and ending angle of the arc, a2 must be greater or equal
+  to a1.
+
+  fl_arc() draws a series of lines to approximate the arc. Notice that the
+  integer version of fl_arc() has a different number of arguments than the
+  double version fl_arc(double x, double y, double r, double start, double a)
+
+  \param[in] x,y,w,h bounding box of complete circle
+  \param[in] a1,a2 start and end angles of arc measured in degrees
+             counter-clockwise from 3 o'clock.  a2 must be greater
+	     than or equal to a1.
+*/
 void fl_arc(int x,int y,int w,int h,double a1,double a2) {
   if (w <= 0 || h <= 0) return;
 #ifdef WIN32
@@ -78,6 +105,18 @@ void fl_arc(int x,int y,int w,int h,double a1,double a2) {
 #endif
 }
 
+/**
+  Draw filled ellipse sections using integer coordinates.
+  
+  Like fl_arc, but fl_pie() draws a filled-in pie slice.
+  This slice may extend outside the line drawn by fl_arc;
+  to avoid this use w - 1 and h - 1.
+
+  \param[in] x,y,w,h bounding box of complete circle
+  \param[in] a1,a2 start and end angles of arc measured in degrees
+             counter-clockwise from 3 o'clock.  a2 must be greater
+	     than or equal to a1.
+*/
 void fl_pie(int x,int y,int w,int h,double a1,double a2) {
   if (w <= 0 || h <= 0) return;
 #ifdef WIN32
diff --git a/src/fl_rect.cxx b/src/fl_rect.cxx
index 251e7751e..71937f507 100644
--- a/src/fl_rect.cxx
+++ b/src/fl_rect.cxx
@@ -45,6 +45,9 @@
 extern float fl_quartz_line_width_;
 #endif
 
+/**
+  Draw a 1-pixel border \e inside the given bounding box
+*/
 void fl_rect(int x, int y, int w, int h) {
   if (w<=0 || h<=0) return;
 #ifdef WIN32
@@ -67,6 +70,9 @@ void fl_rect(int x, int y, int w, int h) {
 #endif
 }
 
+/**
+  Color a rectangle that exactly files the given bounding box
+*/
 void fl_rectf(int x, int y, int w, int h) {
   if (w<=0 || h<=0) return;
 #ifdef WIN32
@@ -88,6 +94,9 @@ void fl_rectf(int x, int y, int w, int h) {
 #endif
 }
 
+/**
+  Draw horizontal line from x,y to x1,y
+*/
 void fl_xyline(int x, int y, int x1) {
 #ifdef WIN32
   MoveToEx(fl_gc, x, y, 0L); LineTo(fl_gc, x1+1, y);
@@ -104,6 +113,9 @@ void fl_xyline(int x, int y, int x1) {
 #endif
 }
 
+/**
+  Draw horizontal line from x,y to x1,y, then vertical from x1,y to x1,y2
+*/
 void fl_xyline(int x, int y, int x1, int y2) {
 #ifdef WIN32
   if (y2 < y) y2--;
@@ -130,6 +142,10 @@ void fl_xyline(int x, int y, int x1, int y2) {
 #endif
 }
 
+/**
+  Draw horizontal line from x,y to x1,y then a vertical from x1,y to x1,y2
+  and then another horizontal from x1,y2 to x3,y2
+*/
 void fl_xyline(int x, int y, int x1, int y2, int x3) {
 #ifdef WIN32
   if(x3 < x1) x3--;
@@ -160,6 +176,9 @@ void fl_xyline(int x, int y, int x1, int y2, int x3) {
 #endif
 }
 
+/**
+  Draw a vertical line from x,y to x,y1
+*/
 void fl_yxline(int x, int y, int y1) {
 #ifdef WIN32
   if (y1 < y) y1--;
@@ -178,6 +197,9 @@ void fl_yxline(int x, int y, int y1) {
 #endif
 }
 
+/**
+  Draw a vertical line from x,y to x,y1 then a horizontal from x,y1 to x2,y1
+*/
 void fl_yxline(int x, int y, int y1, int x2) {
 #ifdef WIN32
   if (x2 > x) x2++;
@@ -204,6 +226,10 @@ void fl_yxline(int x, int y, int y1, int x2) {
 #endif
 }
 
+/**
+  Draw a vertical line from x,y to x,y1 then a horizontal from x,y1 to x2,y1
+  then another vertical from x2,y1 to x2,y3
+*/
 void fl_yxline(int x, int y, int y1, int x2, int y3) {
 #ifdef WIN32
   if(y3<y1) y3--;
@@ -234,6 +260,9 @@ void fl_yxline(int x, int y, int y1, int x2, int y3) {
 #endif
 }
 
+/**
+  Draw a line from x,y to x1,y1
+*/
 void fl_line(int x, int y, int x1, int y1) {
 #ifdef WIN32
   MoveToEx(fl_gc, x, y, 0L); 
@@ -255,6 +284,9 @@ void fl_line(int x, int y, int x1, int y1) {
 #endif
 }
 
+/**
+  Draw a line from x,y to x1,y1 and another from x1,y1 to x2,y2
+*/
 void fl_line(int x, int y, int x1, int y1, int x2, int y2) {
 #ifdef WIN32
   MoveToEx(fl_gc, x, y, 0L); 
@@ -283,6 +315,9 @@ void fl_line(int x, int y, int x1, int y1, int x2, int y2) {
 #endif
 }
 
+/**
+  Outline a 3-sided polygon with lines
+*/
 void fl_loop(int x, int y, int x1, int y1, int x2, int y2) {
 #ifdef WIN32
   MoveToEx(fl_gc, x, y, 0L); 
@@ -310,6 +345,9 @@ void fl_loop(int x, int y, int x1, int y1, int x2, int y2) {
 #endif
 }
 
+/**
+  Outline a 4-sided polygon with lines
+*/
 void fl_loop(int x, int y, int x1, int y1, int x2, int y2, int x3, int y3) {
 #ifdef WIN32
   MoveToEx(fl_gc, x, y, 0L); 
@@ -341,6 +379,9 @@ void fl_loop(int x, int y, int x1, int y1, int x2, int y2, int x3, int y3) {
 #endif
 }
 
+/**
+  Fill a 3-sided polygon. The polygon must be convex.
+*/
 void fl_polygon(int x, int y, int x1, int y1, int x2, int y2) {
   XPoint p[4];
   p[0].x = x;  p[0].y = y;
@@ -372,6 +413,9 @@ void fl_polygon(int x, int y, int x1, int y1, int x2, int y2) {
 #endif
 }
 
+/**
+  Fill a 4-sided polygon. The polygon must be convex.
+*/
 void fl_polygon(int x, int y, int x1, int y1, int x2, int y2, int x3, int y3) {
   XPoint p[5];
   p[0].x = x;  p[0].y = y;
@@ -406,6 +450,9 @@ void fl_polygon(int x, int y, int x1, int y1, int x2, int y2, int x3, int y3) {
 #endif
 }
 
+/**
+  Draw a single pixel at the given coordinates
+*/
 void fl_point(int x, int y) {
 #ifdef WIN32
   SetPixel(fl_gc, x, y, fl_RGB());