Completed Doxygen documentation of Fl_Device, Fl_Abstract_Printer, Fl_Printer classes.

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

10 files changed, 381 insertions, 343 deletions

diff --git a/FL/Fl_Device.H b/FL/Fl_Device.H
index 237d6b5b9..00e6a4768 100644
--- a/FL/Fl_Device.H
+++ b/FL/Fl_Device.H
@@ -49,12 +49,23 @@ extern Fl_Display *fl_display_device;
 typedef void (*Fl_Draw_Image_Cb)(void* ,int,int,int,uchar*);
 
 /**
- @brief A pure virtual class subclassed to send graphics output to display, local files, or printers.
+ \brief A pure virtual class subclassed to send the output of drawing functions to display, printers, or local files.
+ *
+ The protected virtual methods of this class are those that a device should implement to
+ support all of FLTK drawing functions.
+ <br> The preferred FLTK API for drawing operations is the function collection of the 
+ \ref fl_drawings and \ref fl_attributes modules. 
+ <br> Alternatively, member functions of the Fl_Device class can be called
+ using global variable Fl_Device *fl_device that points at all time to the single device 
+ (an instance of an Fl_Device subclass) that's currently receiving drawing requests:<br>
+ <tt>fl_device->rect(x, y, w, h);</tt>
  */
 class Fl_Device {
 protected:
-  int type_;
-  uchar bg_r_, bg_g_, bg_b_; // color for background and/or mixing if particular device does not support masking and/or alpha
+  /** \brief The device type */
+  int type_; 
+  /** \brief color for background and/or mixing if device does not support masking or alpha */
+  uchar bg_r_, bg_g_, bg_b_; 
   friend void fl_rect(int x, int y, int w, int h);
   friend void fl_rectf(int x, int y, int w, int h);
   friend void fl_line_style(int style, int width, char* dashes);
@@ -76,8 +87,6 @@ protected:
   friend void fl_loop(int x0, int y0, int x1, int y1, int x2, int y2, int x3, int y3);
   friend void fl_polygon(int x0, int y0, int x1, int y1, int x2, int y2);
   friend void fl_polygon(int x0, int y0, int x1, int y1, int x2, int y2, int x3, int y3);
-  friend void fl_concat();
-  friend void fl_reconcat();
   friend void fl_begin_points();
   friend void fl_begin_line();
   friend void fl_begin_loop();
@@ -106,58 +115,121 @@ protected:
   friend void fl_draw_image(Fl_Draw_Image_Cb, void*, int,int,int,int, int delta);
   friend void fl_draw_image_mono(Fl_Draw_Image_Cb, void*, int,int,int,int, int delta);
   
+  /** \brief see fl_rect(int x, int y, int w, int h). */
   virtual void rect(int x, int y, int w, int h);
+  /** \brief see fl_rectf(int x, int y, int w, int h). */
   virtual void rectf(int x, int y, int w, int h);
+  /** \brief see fl_line_style(int style, int width, char* dashes). */
   virtual void line_style(int style, int width=0, char* dashes=0);
+  /** \brief see fl_xyline(int x, int y, int x1). */
   virtual void xyline(int x, int y, int x1);
+  /** \brief see fl_xyline(int x, int y, int x1, int y2). */
   virtual void xyline(int x, int y, int x1, int y2);
+  /** \brief see fl_xyline(int x, int y, int x1, int y2, int x3). */
   virtual void xyline(int x, int y, int x1, int y2, int x3);
+  /** \brief see fl_yxline(int x, int y, int y1). */
   virtual void yxline(int x, int y, int y1);
+  /** \brief see fl_yxline(int x, int y, int y1, int x2). */
   virtual void yxline(int x, int y, int y1, int x2);
+  /** \brief see fl_yxline(int x, int y, int y1, int x2, int y3). */
   virtual void yxline(int x, int y, int y1, int x2, int y3);
+  /** \brief see fl_line(int x, int y, int x1, int y1). */
   virtual void line(int x, int y, int x1, int y1);
+  /** \brief see fl_line(int x, int y, int x1, int y1, int x2, int y2). */
   virtual void line(int x, int y, int x1, int y1, int x2, int y2);
+  /** \brief see fl_draw(const char *str, int n, int x, int y). */
   virtual void draw(const char *str, int n, int x, int y);
+  /** \brief see fl_draw(int angle, const char *str, int n, int x, int y). */
   virtual void draw(int angle, const char *str, int n, int x, int y);
+  /** \brief see fl_font(Fl_Font face, Fl_Fontsize size). */
   virtual void font(Fl_Font face, Fl_Fontsize size);
+  /** \brief see fl_color(Fl_Color c). */
   virtual void color(Fl_Color c);
+  /** \brief see fl_color(uchar r, uchar g, uchar b). */
   virtual void color(uchar r, uchar g, uchar b);
+  /** \brief see fl_point(int x, int y). */
   virtual void point(int x, int y);
+  /** \brief see fl_loop(int x0, int y0, int x1, int y1, int x2, int y2). */
   virtual void loop(int x0, int y0, int x1, int y1, int x2, int y2);
+  /** \brief see fl_loop(int x0, int y0, int x1, int y1, int x2, int y2, int x3, int y3). */
   virtual void loop(int x0, int y0, int x1, int y1, int x2, int y2, int x3, int y3);
+  /** \brief see fl_polygon(int x0, int y0, int x1, int y1, int x2, int y2). */
   virtual void polygon(int x0, int y0, int x1, int y1, int x2, int y2);
+  /** \brief see fl_polygon(int x0, int y0, int x1, int y1, int x2, int y2, int x3, int y3). */
   virtual void polygon(int x0, int y0, int x1, int y1, int x2, int y2, int x3, int y3);
+  /** \brief see fl_begin_points(). */
   virtual void begin_points();
+  /** \brief see fl_begin_line(). */
   virtual void begin_line();
+  /** \brief see fl_begin_loop(). */
   virtual void begin_loop();
+  /** \brief see fl_begin_polygon(). */
   virtual void begin_polygon();
+  /** \brief see fl_vertex(double x, double y). */
   virtual void vertex(double x, double y);
+  /** \brief see fl_curve(double x, double y, double x1, double y1, double x2, double y2, double x3, double y3). */
   virtual void curve(double x, double y, double x1, double y1, double x2, double y2, double x3, double y3);
+  /** \brief see fl_circle(double x, double y, double r). */
   virtual void circle(double x, double y, double r);
+  /** \brief see fl_arc(double x, double y, double r, double start, double a). */
   virtual void arc(double x, double y, double r, double start, double a);
+  /** \brief see fl_arc(int x, int y, int w, int h, double a1, double a2). */
   virtual void arc(int x, int y, int w, int h, double a1, double a2);
+  /** \brief see fl_pie(int x, int y, int w, int h, double a1, double a2). */
   virtual void pie(int x, int y, int w, int h, double a1, double a2);
+  /** \brief see fl_end_points(). */
   virtual void end_points();
+  /** \brief see fl_end_line(). */
   virtual void end_line();
+  /** \brief see fl_end_loop(). */
   virtual void end_loop();
+  /** \brief see fl_end_polygon(). */
   virtual void end_polygon();
+  /** \brief see fl_begin_complex_polygon(). */
   virtual void begin_complex_polygon();
+  /** \brief see fl_gap(). */
   virtual void gap();
+  /** \brief see fl_end_complex_polygon(). */
   virtual void end_complex_polygon();
+  /** \brief see fl_transformed_vertex(double x, double y). */
   virtual void transformed_vertex(double x, double y);
+  /** \brief see fl_push_clip(int x, int y, int w, int h). */
   virtual void push_clip(int x, int y, int w, int h);
+  /** \brief see fl_clip_box(int x, int y, int w, int h, int &X, int &Y, int &W, int &H). */
   virtual int clip_box(int x, int y, int w, int h, int &X, int &Y, int &W, int &H);
+  /** \brief see fl_not_clipped(int x, int y, int w, int h). */
   virtual int not_clipped(int x, int y, int w, int h);
+  /** \brief see fl_push_no_clip(). */
   virtual void push_no_clip();
+  /** \brief see fl_pop_clip(). */
   virtual void pop_clip();
   // Images
+  /** \brief see fl_draw_image(const uchar*, int,int,int,int, int delta, int ldelta). */
   virtual   void draw_image(const uchar*, int,int,int,int, int delta=3, int ldelta=0);
+  /** \brief see fl_draw_image_mono(const uchar*, int,int,int,int, int delta, int ldelta). */
   virtual   void draw_image_mono(const uchar*, int,int,int,int, int delta=1, int ld=0);
+  /** \brief see fl_draw_image(Fl_Draw_Image_Cb, void*, int,int,int,int, int delta). */
   virtual   void draw_image(Fl_Draw_Image_Cb, void*, int,int,int,int, int delta=3);
+  /** \brief see fl_draw_image_mono(Fl_Draw_Image_Cb, void*, int,int,int,int, int delta). */
   virtual   void draw_image_mono(Fl_Draw_Image_Cb, void*, int,int,int,int, int delta=1);
   // Image classes
+  /** \brief Draws an Fl_Pixmap object to the device. 
+   *
+   Specifies a bounding box for the image, with the origin (upper left-hand corner) of 
+   the image offset by the cx and cy arguments.
+   */
   virtual   void draw(Fl_Pixmap * pxm,int XP, int YP, int WP, int HP, int cx, int cy);
+  /** \brief Draws an Fl_RGB_Image object to the device. 
+   *
+   Specifies a bounding box for the image, with the origin (upper left-hand corner) of 
+   the image offset by the cx and cy arguments.
+   */
   virtual   void draw(Fl_RGB_Image * rgb,int XP, int YP, int WP, int HP, int cx, int cy);
+  /** \brief Draws an Fl_Bitmap object to the device. 
+   *
+   Specifies a bounding box for the image, with the origin (upper left-hand corner) of 
+   the image offset by the cx and cy arguments.
+   */
   virtual   void draw(Fl_Bitmap * bmp,int XP, int YP, int WP, int HP, int cx, int cy);
   
 public:
diff --git a/FL/Fl_Printer.H b/FL/Fl_Printer.H
index e958c18e7..2899224c3 100644
--- a/FL/Fl_Printer.H
+++ b/FL/Fl_Printer.H
@@ -36,10 +36,10 @@
 #include <stdio.h>
 
 /**
- \brief A virtual class for print support with several platform-dependent implementations.
+ \brief A virtual class for print support with several platform-specific implementations.
  *
  This class has no public constructor: don't instantiate it; use Fl_Printer instead.
- \see class Fl_Printer for most member functions documentation.
+ \see class Fl_Printer for full documentation of member functions.
  */
 class  Fl_Abstract_Printer : public Fl_Device {
    friend class Fl_Pixmap;
@@ -72,19 +72,33 @@ public:
    @return The current target device of graphics calls.
    */
    Fl_Device *set_current(void);
+  /** \brief see Fl_Printer::start_job(int pagecount, int *frompage, int *topage) */
    virtual int start_job(int pagecount, int *frompage = NULL, int *topage = NULL);
+  /** \brief see Fl_Printer::start_page() */
    virtual int start_page(void);
+  /** \brief see Fl_Printer::printable_rect(int *w, int *h) */
    virtual int printable_rect(int *w, int *h);
+  /** \brief see Fl_Printer::margins(int *left, int *top, int *right, int *bottom) */
    virtual void margins(int *left, int *top, int *right, int *bottom);
+  /** \brief see Fl_Printer::origin(int x, int y) */
    virtual void origin(int x, int y);
+  /** \brief see Fl_Printer::origin(int *x, int *y) */
    void origin(int *x, int *y);
-   virtual void scale (float scale_x, float scale_y);
+  /** \brief see Fl_Printer::scale(float scale_x, float scale_y) */
+   virtual void scale(float scale_x, float scale_y);
+  /** \brief see Fl_Printer::rotate(float angle) */
    virtual void rotate(float angle);
+  /** \brief see Fl_Printer::translate(int x, int y) */
    virtual void translate(int x, int y);
+  /** \brief see Fl_Printer::untranslate(void) */
    virtual void untranslate(void);
+  /** \brief see Fl_Printer::print_widget(Fl_Widget* widget, int delta_x, int delta_y) */
    void print_widget(Fl_Widget* widget, int delta_x = 0, int delta_y = 0);
+  /** \brief see Fl_Printer::print_window_part(Fl_Window *win, int x, int y, int w, int h, int delta_x, int delta_y) */
    void print_window_part(Fl_Window *win, int x, int y, int w, int h, int delta_x = 0, int delta_y = 0);
+  /** \brief see Fl_Printer::end_page() */
    virtual int end_page (void);
+  /** \brief see Fl_Printer::end_job() */
    virtual void end_job (void);
 };
 
@@ -230,7 +244,7 @@ public:
    The widget's position on the printed page is determined by the last call to origin()
    and by the optional delta_x and delta_y arguments.
    Its dimensions are in points unless there was a previous call to scale().
-   <br>Under MSWindows, Fl_RGB_Image's are printed without transparency.
+   <br>Under MSWindows and X11, Fl_RGB_Image's are printed without transparency.
    A workaround is to use the print_window_part() call. 
    @param[in] widget Any FLTK widget (e.g., standard, custom, window).
    @param[in] delta_x Optional horizontal offset for positioning the widget relatively
diff --git a/FL/fl_draw.H b/FL/fl_draw.H
index 4ed13143c..fc6b54136 100644
--- a/FL/fl_draw.H
+++ b/FL/fl_draw.H
@@ -47,12 +47,30 @@ extern Fl_Device *fl_device;
 /** \addtogroup fl_attributes
     @{
 */
+
 // Colors:
-//FL_EXPORT void	fl_color(Fl_Color i); // select indexed color
+/**
+ Sets the color for all subsequent drawing operations.
+ For colormapped displays, a color cell will be allocated out of
+ \p fl_colormap the first time you use a color. If the colormap fills up
+ then a least-squares algorithm is used to find the closest color.
+ If no valid graphical context (fl_gc) is available,
+ the foreground is not set for the current window.
+ \param[in] i color 
+ */
 inline void	fl_color(Fl_Color i) {fl_device->color(i); }; // select indexed color
 /** for back compatibility - use fl_color(Fl_Color c) instead */
 inline void fl_color(int c) {fl_color((Fl_Color)c);}
-//FL_EXPORT void	fl_color(uchar r, uchar g, uchar b); // select actual color
+/**
+ Set the color for all subsequent drawing operations.
+ The closest possible match to the RGB color is used.
+ The RGB color is used directly on TrueColor displays.
+ For colormap visuals the nearest index in the gray
+ ramp or color cube is used.
+ If no valid graphical context (fl_gc) is available,
+ the foreground is not set for the current window.
+ \param[in] r,g,b color components
+ */
 inline void	fl_color(uchar r, uchar g, uchar b) {fl_device->color(r,g,b); }; // select actual color
 extern FL_EXPORT Fl_Color fl_color_;
 /**
@@ -66,26 +84,102 @@ inline Fl_Color fl_color() {return fl_color_;}
     @{
 */
 // clip:
-//FL_EXPORT void fl_push_clip(int x, int y, int w, int h);
+/**
+ Intersects the current clip region with a rectangle and pushes this
+ new region onto the stack.
+ \param[in] x,y,w,h position and size
+ */
 inline void fl_push_clip(int x, int y, int w, int h) {fl_device->push_clip(x,y,w,h); };
 /** The fl_clip() name is deprecated and will be removed from future releases */
 #define fl_clip fl_push_clip
-//FL_EXPORT void fl_push_no_clip();
+/**
+ Pushes an empty clip region onto the stack so nothing will be clipped.
+ */
 inline void fl_push_no_clip() {fl_device->push_no_clip(); };
-//FL_EXPORT void fl_pop_clip();
+/**
+ Restores the previous clip region.
+ 
+ You must call fl_pop_clip() once for every time you call fl_push_clip().
+ Unpredictable results may occur if the clip stack is not empty when
+ you return to FLTK.
+ */
 inline void fl_pop_clip() {fl_device->pop_clip(); };
-//FL_EXPORT int fl_not_clipped(int x, int y, int w, int h);
+/**
+ Does the rectangle intersect the current clip region?
+ \param[in] x,y,w,h position and size of rectangle
+ \returns non-zero if any of the rectangle intersects the current clip
+ region. If this returns 0 you don't have to draw the object.
+ 
+ \note
+ Under X this returns 2 if the rectangle is partially clipped, 
+ and 1 if it is entirely inside the clip region.
+ */
 inline int fl_not_clipped(int x, int y, int w, int h) {return fl_device->not_clipped(x,y,w,h); };
-//FL_EXPORT int fl_clip_box(int, int, int, int, int& x, int& y, int& w, int& h);
+/**
+ Intersects the rectangle with the current clip region and returns the
+ bounding box of the result.
+ 
+ Returns non-zero if the resulting rectangle is different to the original.
+ This can be used to limit the necessary drawing to a rectangle.
+ \p W and \p H are set to zero if the rectangle is completely outside
+ the region.
+ \param[in] x,y,w,h position and size of rectangle
+ \param[out] X,Y,W,H position and size of resulting bounding box.
+ \p W and \p H are set to zero if the rectangle is
+ completely outside the region.
+ \returns Non-zero if the resulting rectangle is different to the original.
+ */
 inline int fl_clip_box(int x , int y, int w, int h, int& X, int& Y, int& W, int& H) 
   {return fl_device->clip_box(x,y,w,h,X,Y,W,H); };
+/** Undoes any clobbering of clip done by your program */
+extern void fl_restore_clip();
+/**
+ Replaces the top of the clipping stack with a clipping region of any shape.
+ 
+ Fl_Region is an operating system specific type.
+ \param[in] r clipping region
+ */
+extern void fl_clip_region(Fl_Region r);
+/**
+ returns the current clipping region.
+ */
+extern Fl_Region fl_clip_region();
+  
 
 // points:
-//FL_EXPORT void fl_point(int x, int y);
+/**
+ Draws a single pixel at the given coordinates
+ */
 inline void fl_point(int x, int y) { fl_device->point(x,y); };
 
 // line type:
-//FL_EXPORT void fl_line_style(int style, int width=0, char* dashes=0);
+/**
+ Sets 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 gap, 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 \p dashes array does not work under Windows 95, 98 or Me,
+ since those operating systems do not support complex line styles.
+ */
 inline void fl_line_style(int style, int width=0, char* dashes=0) {fl_device->line_style(style,width,dashes); };
 enum {
   FL_SOLID	= 0,		///< line style: <tt>___________</tt>
@@ -104,13 +198,15 @@ enum {
 };
 
 // rectangles tweaked to exactly fill the pixel rectangle:
-//FL_EXPORT void fl_rect(int x, int y, int w, int h);
-inline void fl_rect(int x, int y, int w, int h) { fl_device->rect(x,y,w,h); };
+
 /** Draws a 1-pixel border \e inside the given bounding box */
+inline void fl_rect(int x, int y, int w, int h) { fl_device->rect(x,y,w,h); };
+
+/** Draws with passed color 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);
+/** Colors with current color a rectangle that exactly fills the given bounding box */
 inline void fl_rectf(int x, int y, int w, int h) { fl_device->rectf(x,y,w,h); };
-/** Colors a rectangle that exactly fills the given bounding box */
+/** Colors with passsed 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);}
 
 /**
@@ -123,45 +219,103 @@ inline void fl_rectf(int x, int y, int w, int h, Fl_Color c) {fl_color(c); fl_re
 FL_EXPORT void fl_rectf(int x, int y, int w, int h, uchar r, uchar g, uchar b);
 
 // line segments:
-//FL_EXPORT void fl_line(int x, int y, int x1, int y1);
+/**
+ Draws a line from (x,y) to (x1,y1)
+ */
 inline void fl_line(int x, int y, int x1, int y1) {fl_device->line(x,y,x1,y1); };
-//FL_EXPORT void fl_line(int x, int y, int x1, int y1, int x2, int y2);
+/**
+ Draws a line from (x,y) to (x1,y1) and another from (x1,y1) to (x2,y2)
+ */
 inline void fl_line(int x, int y, int x1, int y1, int x2, int y2) {fl_device->line(x,y,x1,y1,x2,y2); };
 
 // closed line segments:
-//FL_EXPORT void fl_loop(int x, int y, int x1, int y1, int x2, int y2);
+/**
+ Outlines a 3-sided polygon with lines
+ */
 inline void fl_loop(int x, int y, int x1, int y1, int x2, int y2) {fl_device->loop(x,y,x1,y1,x2,y2); };
-//FL_EXPORT void fl_loop(int x, int y, int x1, int y1, int x2, int y2, int x3, int y3);
+/**
+ Outlines a 4-sided polygon with lines
+ */
 inline void fl_loop(int x, int y, int x1, int y1, int x2, int y2, int x3, int y3) 
   {fl_device->loop(x,y,x1,y1,x2,y2,x3,y3); };
 
 // filled polygons
-//FL_EXPORT void fl_polygon(int x, int y, int x1, int y1, int x2, int y2);
+/**
+ Fills a 3-sided polygon. The polygon must be convex.
+ */
 inline void fl_polygon(int x, int y, int x1, int y1, int x2, int y2) {fl_device->polygon(x,y,x1,y1,x2,y2); };
-//FL_EXPORT void fl_polygon(int x, int y, int x1, int y1, int x2, int y2, int x3, int y3);
+/**
+ Fills a 4-sided polygon. The polygon must be convex.
+ */
 inline void fl_polygon(int x, int y, int x1, int y1, int x2, int y2, int x3, int y3) 
   { fl_device->polygon(x,y,x1,y1,x2,y2,x3,y3); };
 
 // draw rectilinear lines, horizontal segment first:
-//FL_EXPORT void fl_xyline(int x, int y, int x1);
+/**
+ Draws a horizontal line from (x,y) to (x1,y)
+ */
 inline void fl_xyline(int x, int y, int x1) {fl_device->xyline(x,y,x1);};
-//FL_EXPORT void fl_xyline(int x, int y, int x1, int y2);
+/**
+ Draws a horizontal line from (x,y) to (x1,y), then vertical from (x1,y) to (x1,y2)
+ */
 inline void fl_xyline(int x, int y, int x1, int y2) {fl_device->xyline(x,y,x1,y2);};
-//FL_EXPORT void fl_xyline(int x, int y, int x1, int y2, int x3);
+/**
+ Draws a 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)
+ */
 inline void fl_xyline(int x, int y, int x1, int y2, int x3) {fl_device->xyline(x,y,x1,y2,x3);};
 
 // draw rectilinear lines, vertical segment first:
-//FL_EXPORT void fl_yxline(int x, int y, int y1);
+/**
+ Draws a vertical line from (x,y) to (x,y1)
+ */
 inline void fl_yxline(int x, int y, int y1) {fl_device->yxline(x,y,y1);};
-//FL_EXPORT void fl_yxline(int x, int y, int y1, int x2);
+/**
+ Draws a vertical line from (x,y) to (x,y1), then a horizontal from (x,y1) to (x2,y1)
+ */
 inline void fl_yxline(int x, int y, int y1, int x2) {fl_device->yxline(x,y,y1,x2);};
-//FL_EXPORT void fl_yxline(int x, int y, int y1, int x2, int y3);
+/**
+ Draws 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)
+ */
 inline void fl_yxline(int x, int y, int y1, int x2, int y3) {fl_device->yxline(x,y,y1,x2,y3);};
 
 // circular lines and pie slices (code in fl_arci.C):
-//FL_EXPORT void fl_arc(int x, int y, int w, int h, double a1, double a2);
+/**
+ 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 o'clock and
+ are the starting and ending angle of the arc, \p a2 must be greater or equal
+ to \p 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. \p a2 must be greater
+ than or equal to \p a1.
+ */
 inline void fl_arc(int x, int y, int w, int h, double a1, double a2) {fl_device->arc(x,y,w,h,a1,a2); };
-//FL_EXPORT void fl_pie(int x, int y, int w, int h, double a1, double a2);
+/**
+ 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. \p a2 must be greater
+ than or equal to \p a1.
+ */
 inline void fl_pie(int x, int y, int w, int h, double a1, double a2) {fl_device->pie(x,y,w,h,a1,a2); };
 /** fl_chord declaration is a place holder - the function does not yet exist */
 FL_EXPORT void fl_chord(int x, int y, int w, int h, double a1, double a2); // nyi
@@ -174,49 +328,113 @@ FL_EXPORT void fl_scale(double x);
 FL_EXPORT void fl_translate(double x, double y);
 FL_EXPORT void fl_rotate(double d);
 FL_EXPORT void fl_mult_matrix(double a, double b, double c, double d, double x,double y);
-//FL_EXPORT void fl_begin_points();
+/**
+ Starts drawing a list of points. Points are added to the list with fl_vertex()
+ */
 inline void fl_begin_points() {fl_device->begin_points(); };
-//FL_EXPORT void fl_begin_line();
+/**
+ Starts drawing a list of lines.
+ */
 inline void fl_begin_line() {fl_device->begin_line(); };
-//FL_EXPORT void fl_begin_loop();
+/**
+ Starts drawing a closed sequence of lines.
+ */
 inline void fl_begin_loop() {fl_device->begin_loop(); };
-//FL_EXPORT void fl_begin_polygon();
+/**
+ Starts drawing a convex filled polygon.
+ */
 inline void fl_begin_polygon() {fl_device->begin_polygon(); };
-//FL_EXPORT void fl_vertex(double x, double y);
+/**
+ Adds a single vertex to the current path.
+ \param[in] x,y coordinate
+ */
 inline void fl_vertex(double x, double y) {fl_device->vertex(x,y); };
-//FL_EXPORT void fl_curve(double X0, double Y0, double X1, double Y1, double X2, double Y2, double X3, double Y3);
+/**
+ Add a series of points on a Bezier curve to the path.
+ The curve ends (and two of the points) are at X0,Y0 and X3,Y3.
+ \param[in] X0,Y0 curve start point
+ \param[in] X1,Y1 curve control point
+ \param[in] X2,Y2 curve control point
+ \param[in] X3,Y3 curve end point
+ */
 inline void fl_curve(double X0, double Y0, double X1, double Y1, double X2, double Y2, double X3, double Y3)
   {fl_device->curve(X0,Y0,X1,Y1,X2,Y2,X3,Y3); };
-//FL_EXPORT void fl_arc(double x, double y, double r, double start, double a);
-inline void fl_arc(double x, double y, double r, double start, double a) {fl_device->arc(x,y,r,start,a); };
-//FL_EXPORT void fl_circle(double x, double y, double r);
+/**
+ 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 \p end is less than \p start
+ then it draws the arc in a clockwise direction.
+ */
+inline void fl_arc(double x, double y, double r, double start, double end) {fl_device->arc(x,y,r,start,end); };
+/**
+ fl_circle() is equivalent to fl_arc(x,y,r,0,360), but may be faster.
+ 
+ It must be the \e only thing in the path: if you want a circle as part of
+ a complex polygon you must use fl_arc()
+ \param[in] x,y,r center and radius of circle
+ */
 inline void fl_circle(double x, double y, double r) {fl_device->circle(x,y,r); };
-//FL_EXPORT void fl_end_points();
+/**
+ Ends list of points, and draws.
+ */
 inline void fl_end_points() {fl_device->end_points(); };
-//FL_EXPORT void fl_end_line();
+/**
+ Ends list of lines, and draws.
+ */
 inline void fl_end_line() {fl_device->end_line(); };
-//FL_EXPORT void fl_end_loop();
+/**
+ Ends closed sequence of lines, and draws.
+ */
 inline void fl_end_loop() {fl_device->end_loop(); };
-//FL_EXPORT void fl_end_polygon();
+/**
+ Ends convex filled polygon, and draws.
+ */
 inline void fl_end_polygon() {fl_device->end_polygon(); };
-//FL_EXPORT void fl_begin_complex_polygon();
+/**
+ Starts drawing a complex filled polygon.
+ 
+ The polygon may be concave, may have holes in it, or may be several
+ disconnected pieces. Call fl_gap() to separate loops of the path.
+ 
+ To outline the polygon, use fl_begin_loop() and replace each fl_gap()
+ with fl_end_loop();fl_begin_loop() pairs.
+ 
+ \note
+ For portability, you should only draw polygons that appear the same
+ whether "even/odd" or "non-zero" winding rules are used to fill them.
+ Holes should be drawn in the opposite direction to the outside loop.
+ */
 inline void fl_begin_complex_polygon() {fl_device->begin_complex_polygon(); };
-//FL_EXPORT void fl_gap();
+/**
+ Call fl_gap() to separate loops of the path.
+ 
+ It is unnecessary but harmless to call fl_gap() before the first vertex,
+ after the last vertex, or several times in a row.
+ */
 inline void fl_gap() {fl_device->gap(); };
-//FL_EXPORT void fl_end_complex_polygon();
+/**
+ Ends complex filled polygon, and draws.
+ */
 inline void fl_end_complex_polygon() {fl_device->end_complex_polygon(); };
 // get and use transformed positions:
 FL_EXPORT double fl_transform_x(double x, double y);
 FL_EXPORT double fl_transform_y(double x, double y);
 FL_EXPORT double fl_transform_dx(double x, double y);
 FL_EXPORT double fl_transform_dy(double x, double y);
-//FL_EXPORT void fl_transformed_vertex(double x, double y);
-inline void fl_transformed_vertex(double x, double y) {fl_device->transformed_vertex(x,y); };
+/**
+ Adds coordinate pair to the vertex list without further transformations.
+ \param[in] xf,yf transformed coordinate
+ */
+inline void fl_transformed_vertex(double xf, double yf) {fl_device->transformed_vertex(xf,yf); };
 /** @} */
 
 /** \addtogroup  fl_attributes
     @{ */
 /* NOTE: doxygen comments here to avoid triplication in os-specific sources */
+
+// Fonts:
 /**
   Sets the current font, which is then used in various drawing routines.
   You may call this outside a draw context if necessary to call fl_width(),
@@ -226,9 +444,6 @@ inline void fl_transformed_vertex(double x, double y) {fl_device->transformed_ve
   The size of the font is measured in pixels and not "points".
   Lines should be spaced \p size pixels apart or more.
 */
-
-// Fonts:
-//FL_EXPORT void fl_font(Fl_Font face, Fl_Fontsize size);
 inline void fl_font(Fl_Font face, Fl_Fontsize size) { fl_device->font(face,size); };
 extern FL_EXPORT Fl_Font fl_font_; ///< current font index
 
@@ -324,25 +539,22 @@ FL_EXPORT const char *fl_local_to_mac_roman(const char *t, int n=-1);
   to control characters.
 */
 FL_EXPORT void fl_draw(const char* str, int x, int y);
-FL_EXPORT void fl_draw(int angle, const char* str, int x, int y);
 /**
   Draws a nul-terminated string starting at the given location and 
   rotating \p angle degrees counterclockwise.
   This version of fl_draw provides direct access to the text drawing
-  function of the underlying OS and suported for Xft, Win32 and MacOS
-  fltk subset.
+  function of the underlying OS and is supported by Xft, Win32 and MacOS
+  fltk subsets.
 */
-//FL_EXPORT void fl_draw(int angle,const char* str, int x, int y);
+FL_EXPORT void fl_draw(int angle, const char* str, int x, int y);
 /**
   Draws an array of \p n characters starting at the given location.
 */
-//FL_EXPORT void fl_draw(const char* str, int n, int x, int y);
 inline void fl_draw(const char* str, int n, int x, int y) {fl_device->draw(str,n,x,y); };
 /**
   Draws an array of \p n characters starting at the given location,
   rotating \p angle degrees counterclockwise.
 */
-//FL_EXPORT void fl_draw(int angle,const char* str, int n, int x, int y);
 inline void fl_draw(int angle,const char* str, int n, int x, int y) {fl_device->draw(angle,str,n,x,y); };
 /**
   Draws an array of \p n characters right to left starting at given location.
diff --git a/src/fl_arc.cxx b/src/fl_arc.cxx
index 6b0cb13ea..0ee4269a4 100644
--- a/src/fl_arc.cxx
+++ b/src/fl_arc.cxx
@@ -43,14 +43,6 @@ 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 \p end is less than \p start
-	     then it draws the arc in a clockwise direction.
-*/
 void Fl_Device::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 81414599c..c41ce1d20 100644
--- a/src/fl_arci.cxx
+++ b/src/fl_arci.cxx
@@ -47,28 +47,6 @@
 #endif
 #include <config.h>
 
-/**
-  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 o'clock and
-  are the starting and ending angle of the arc, \p a2 must be greater or equal
-  to \p 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. \p a2 must be greater
-	     than or equal to \p a1.
-*/
 void Fl_Device::arc(int x,int y,int w,int h,double a1,double a2) {
   if (w <= 0 || h <= 0) return;
 
@@ -108,18 +86,6 @@ void Fl_Device::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. \p a2 must be greater
-	     than or equal to \p a1.
-*/
 void Fl_Device::pie(int x,int y,int w,int h,double a1,double a2) {
   if (w <= 0 || h <= 0) return;
 
diff --git a/src/fl_color.cxx b/src/fl_color.cxx
index 33f92478d..735757427 100644
--- a/src/fl_color.cxx
+++ b/src/fl_color.cxx
@@ -124,6 +124,26 @@ Fl_XColor fl_xmap[1][256];
 #    define fl_overlay 0
 #  endif
 
+/** Current color for drawing operations */
+Fl_Color fl_color_;
+
+void Fl_Device::color(Fl_Color i) {
+  if (i & 0xffffff00) {
+    unsigned rgb = (unsigned)i;
+    fl_color((uchar)(rgb >> 24), (uchar)(rgb >> 16), (uchar)(rgb >> 8));
+  } else {
+    fl_color_ = i;
+    if(!fl_gc) return; // don't get a default gc if current window is not yet created/valid
+    XSetForeground(fl_display, fl_gc, fl_xpixel(i));
+  }
+}
+
+void Fl_Device::color(uchar r,uchar g,uchar b) {
+  fl_color_ = fl_rgb_color(r, g, b);
+  if(!fl_gc) return; // don't get a default gc if current window is not yet created/valid
+  XSetForeground(fl_display, fl_gc, fl_xpixel(r,g,b));
+}
+
 /** \addtogroup  fl_attributes
     @{ */
 ////////////////////////////////////////////////////////////////
@@ -161,22 +181,6 @@ ulong fl_xpixel(uchar r,uchar g,uchar b) {
      ) >> fl_extrashift;
 }
 
-/**
-  Set the color for all subsequent drawing operations.
-  The closest possible match to the RGB color is used.
-  The RGB color is used directly on TrueColor displays.
-  For colormap visuals the nearest index in the gray
-  ramp or color cube is used.
-  If no valid graphical context (fl_gc) is available,
-  the foreground is not set for the current window.
-  \param[in] r,g,b color components
-*/
-void Fl_Device::color(uchar r,uchar g,uchar b) {
-  fl_color_ = fl_rgb_color(r, g, b);
-  if(!fl_gc) return; // don't get a default gc if current window is not yet created/valid
-  XSetForeground(fl_display, fl_gc, fl_xpixel(r,g,b));
-}
-
 ////////////////////////////////////////////////////////////////
 // Get a color out of the fltk colormap.  Again for truecolor
 // visuals this is easy.  For colormap this actually tries to allocate
@@ -316,29 +320,6 @@ ulong fl_xpixel(Fl_Color i) {
 #  endif
 }
 
-/** Current color for drawing operations */
-Fl_Color fl_color_;
-
-/**
-  Sets the color for all subsequent drawing operations.
-  For colormapped displays, a color cell will be allocated out of
-  \p fl_colormap the first time you use a color. If the colormap fills up
-  then a least-squares algorithm is used to find the closest color.
-  If no valid graphical context (fl_gc) is available,
-  the foreground is not set for the current window.
-  \param[in] i color 
-*/
-void Fl_Device::color(Fl_Color i) {
-  if (i & 0xffffff00) {
-    unsigned rgb = (unsigned)i;
-    fl_color((uchar)(rgb >> 24), (uchar)(rgb >> 16), (uchar)(rgb >> 8));
-  } else {
-    fl_color_ = i;
-    if(!fl_gc) return; // don't get a default gc if current window is not yet created/valid
-    XSetForeground(fl_display, fl_gc, fl_xpixel(i));
-  }
-}
-
 /**
   Free color \p i if used, and clear mapping table entry.
   \param[in] i color index
diff --git a/src/fl_curve.cxx b/src/fl_curve.cxx
index c6663a739..d9406787e 100644
--- a/src/fl_curve.cxx
+++ b/src/fl_curve.cxx
@@ -38,14 +38,6 @@
 #include <FL/fl_draw.H>
 #include <math.h>
 
-/**
-  Add a series of points on a Bezier curve to the path.
-  The curve ends (and two of the points) are at X0,Y0 and X3,Y3.
-  \param[in] X0,Y0 curve start point
-  \param[in] X1,Y1 curve control point
-  \param[in] X2,Y2 curve control point
-  \param[in] X3,Y3 curve end point
-*/
 void Fl_Device::curve(double X0, double Y0,
 	      double X1, double Y1,
 	      double X2, double Y2,
diff --git a/src/fl_line_style.cxx b/src/fl_line_style.cxx
index b73074323..e93f159ec 100644
--- a/src/fl_line_style.cxx
+++ b/src/fl_line_style.cxx
@@ -50,33 +50,6 @@ void fl_quartz_restore_line_style_() {
 }
 #endif
 
-/**
-  Sets 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 gap, 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 \p dashes array does not work under Windows 95, 98 or Me,
-             since those operating systems do not support complex line styles.
-*/
 void Fl_Device::line_style(int style, int width, char* dashes) {
 
 #if defined(USE_X11)
diff --git a/src/fl_rect.cxx b/src/fl_rect.cxx
index 4585fe334..9ec3fcc4f 100644
--- a/src/fl_rect.cxx
+++ b/src/fl_rect.cxx
@@ -48,9 +48,6 @@ extern float fl_quartz_line_width_;
 #endif
 #endif
 
-/**
-  Draws a 1-pixel border \e inside the given bounding box
-*/
 void Fl_Device::rect(int x, int y, int w, int h) {
 
   if (w<=0 || h<=0) return;
@@ -80,9 +77,6 @@ void Fl_Device::rect(int x, int y, int w, int h) {
 #endif
 }
 
-/**
-  Colors a rectangle that exactly fills the given bounding box
-*/
 void Fl_Device::rectf(int x, int y, int w, int h) {
   if (w<=0 || h<=0) return;
 #if defined(USE_X11)
@@ -110,9 +104,6 @@ void Fl_Device::rectf(int x, int y, int w, int h) {
 #endif
 }
 
-/**
-  Draws a horizontal line from (x,y) to (x1,y)
-*/
 void Fl_Device::xyline(int x, int y, int x1) {
 #if defined(USE_X11)
   XDrawLine(fl_display, fl_window, fl_gc, x, y, x1, y);
@@ -137,9 +128,6 @@ void Fl_Device::xyline(int x, int y, int x1) {
 #endif
 }
 
-/**
-  Draws a horizontal line from (x,y) to (x1,y), then vertical from (x1,y) to (x1,y2)
-*/
 void Fl_Device::xyline(int x, int y, int x1, int y2) {
 #if defined (USE_X11)
   XPoint p[3];
@@ -172,10 +160,6 @@ void Fl_Device::xyline(int x, int y, int x1, int y2) {
 #endif
 }
 
-/**
-  Draws a 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_Device::xyline(int x, int y, int x1, int y2, int x3) {
 #if defined(USE_X11)
   XPoint p[4];
@@ -211,9 +195,6 @@ void Fl_Device::xyline(int x, int y, int x1, int y2, int x3) {
 #endif
 }
 
-/**
-  Draws a vertical line from (x,y) to (x,y1)
-*/
 void Fl_Device::yxline(int x, int y, int y1) {
 #if defined(USE_X11)
   XDrawLine(fl_display, fl_window, fl_gc, x, y, x, y1);
@@ -240,9 +221,6 @@ void Fl_Device::yxline(int x, int y, int y1) {
 #endif
 }
 
-/**
-  Draws a vertical line from (x,y) to (x,y1), then a horizontal from (x,y1) to (x2,y1)
-*/
 void Fl_Device::yxline(int x, int y, int y1, int x2) {
 #if defined(USE_X11)
   XPoint p[3];
@@ -275,10 +253,6 @@ void Fl_Device::yxline(int x, int y, int y1, int x2) {
 #endif
 }
 
-/**
-  Draws 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_Device::yxline(int x, int y, int y1, int x2, int y3) {
 #if defined(USE_X11)
   XPoint p[4];
@@ -314,9 +288,6 @@ void Fl_Device::yxline(int x, int y, int y1, int x2, int y3) {
 #endif
 }
 
-/**
-  Draws a line from (x,y) to (x1,y1)
-*/
 void Fl_Device::line(int x, int y, int x1, int y1) {
 #if defined(USE_X11)
   XDrawLine(fl_display, fl_window, fl_gc, x, y, x1, y1);
@@ -345,9 +316,6 @@ void Fl_Device::line(int x, int y, int x1, int y1) {
 #endif
 }
 
-/**
-  Draws a line from (x,y) to (x1,y1) and another from (x1,y1) to (x2,y2)
-*/
 void Fl_Device::line(int x, int y, int x1, int y1, int x2, int y2) {
 #if defined(USE_X11)
   XPoint p[3];
@@ -382,9 +350,6 @@ void Fl_Device::line(int x, int y, int x1, int y1, int x2, int y2) {
 #endif
 }
 
-/**
-  Outlines a 3-sided polygon with lines
-*/
 void Fl_Device::loop(int x, int y, int x1, int y1, int x2, int y2) {
 #if defined(USE_X11)
   XPoint p[4];
@@ -415,9 +380,6 @@ void Fl_Device::loop(int x, int y, int x1, int y1, int x2, int y2) {
 #endif
 }
 
-/**
-  Outlines a 4-sided polygon with lines
-*/
 void Fl_Device::loop(int x, int y, int x1, int y1, int x2, int y2, int x3, int y3) {
 #if defined(USE_X11)
   XPoint p[5];
@@ -451,9 +413,6 @@ void Fl_Device::loop(int x, int y, int x1, int y1, int x2, int y2, int x3, int y
 #endif
 }
 
-/**
-  Fills a 3-sided polygon. The polygon must be convex.
-*/
 void Fl_Device::polygon(int x, int y, int x1, int y1, int x2, int y2) {
   XPoint p[4];
   p[0].x = x;  p[0].y = y;
@@ -483,9 +442,6 @@ void Fl_Device::polygon(int x, int y, int x1, int y1, int x2, int y2) {
 #endif
 }
 
-/**
-  Fills a 4-sided polygon. The polygon must be convex.
-*/
 void Fl_Device::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;
@@ -517,9 +473,6 @@ void Fl_Device::polygon(int x, int y, int x1, int y1, int x2, int y2, int x3, in
 #endif
 }
 
-/**
-  Draws a single pixel at the given coordinates
-*/
 void Fl_Device::point(int x, int y) {
 #if defined(USE_X11)
   XDrawPoint(fl_display, fl_window, fl_gc, x, y);
@@ -564,13 +517,6 @@ Fl_Region XRectangleRegion(int x, int y, int w, int h) {
 }
 #endif
 
-#if defined(__APPLE_QUARTZ__)
-// warning: the Quartz implementation currently uses Quickdraw calls to achieve
-//          clipping. A future version should instead use 'CGContectClipToRect'
-//          and friends.
-#endif
-
-/** Undoes any clobbering of clip done by your program */
 void fl_restore_clip() {
   fl_clip_state_number++;
   Fl_Region r = rstack[rstackptr];
@@ -624,12 +570,6 @@ void fl_restore_clip() {
 #endif
 }
 
-/**
-  Replaces the top of the clipping stack with a clipping region of any shape.
-
-  Fl_Region is an operating system specific type.
-  \param[in] r clipping region
-*/
 void fl_clip_region(Fl_Region r) {
   Fl_Region oldr = rstack[rstackptr];
   if (oldr) XDestroyRegion(oldr);
@@ -637,18 +577,10 @@ void fl_clip_region(Fl_Region r) {
   fl_restore_clip();
 }
 
-/**
-  \returns the current clipping region.
-*/
 Fl_Region fl_clip_region() {
   return rstack[rstackptr];
 }
 
-/**
-  Intersects the current clip region with a rectangle and pushes this
-  new region onto the stack.
-  \param[in] x,y,w,h position and size
-*/
 void Fl_Device::push_clip(int x, int y, int w, int h) {
   Fl_Region r;
   if (w > 0 && h > 0) {
@@ -695,9 +627,6 @@ void Fl_Device::push_clip(int x, int y, int w, int h) {
 }
 
 // make there be no clip (used by fl_begin_offscreen() only!)
-/**
-  Pushes an empty clip region onto the stack so nothing will be clipped.
-*/
 void Fl_Device::push_no_clip() {
   if (rstackptr < STACK_MAX) rstack[++rstackptr] = 0;
   else Fl::warning("fl_push_no_clip: clip stack overflow!\n");
@@ -705,13 +634,6 @@ void Fl_Device::push_no_clip() {
 }
 
 // pop back to previous clip:
-/**
-  Restores the previous clip region.
-
-  You must call fl_pop_clip() once for every time you call fl_push_clip().
-  Unpredictable results may occur if the clip stack is not empty when
-  you return to FLTK.
-*/
 void Fl_Device::pop_clip() {
   if (rstackptr > 0) {
     Fl_Region oldr = rstack[rstackptr--];
@@ -720,16 +642,6 @@ void Fl_Device::pop_clip() {
   fl_restore_clip();
 }
 
-/**
-  Does the rectangle intersect the current clip region?
-  \param[in] x,y,w,h position and size of rectangle
-  \returns non-zero if any of the rectangle intersects the current clip
-  region. If this returns 0 you don't have to draw the object.
-
-  \note
-  Under X this returns 2 if the rectangle is partially clipped, 
-  and 1 if it is entirely inside the clip region.
-*/
 int Fl_Device::not_clipped(int x, int y, int w, int h) {
   if (x+w <= 0 || y+h <= 0) return 0;
   Fl_Region r = rstack[rstackptr];
@@ -767,20 +679,6 @@ int Fl_Device::not_clipped(int x, int y, int w, int h) {
 }
 
 // return rectangle surrounding intersection of this rectangle and clip:
-/**
-  Intersects the rectangle with the current clip region and returns the
-  bounding box of the result.
-
-  Returns non-zero if the resulting rectangle is different to the original.
-  This can be used to limit the necessary drawing to a rectangle.
-  \p W and \p H are set to zero if the rectangle is completely outside
-  the region.
-  \param[in] x,y,w,h position and size of rectangle
-  \param[out] X,Y,W,H position and size of resulting bounding box.
-              \p W and \p H are set to zero if the rectangle is
-	      completely outside the region.
-  \returns Non-zero if the resulting rectangle is different to the original.
-*/
 int Fl_Device::clip_box(int x, int y, int w, int h, int& X, int& Y, int& W, int& H){
   X = x; Y = y; W = w; H = h;
   Fl_Region r = rstack[rstackptr];
diff --git a/src/fl_vertex.cxx b/src/fl_vertex.cxx
index d2823391d..9aafae4de 100644
--- a/src/fl_vertex.cxx
+++ b/src/fl_vertex.cxx
@@ -145,24 +145,12 @@ static int n;
 static int what;
 enum {LINE, LOOP, POLYGON, POINT_};
 
-/**
-  Starts drawing a list of points. Points are added to the list with fl_vertex()
-*/
 void Fl_Device::begin_points() {n = 0; what = POINT_;}
 
-/**
-  Starts drawing a list of lines.
-*/
 void Fl_Device::begin_line() {n = 0; what = LINE;}
 
-/**
-  Starts drawing a closed sequence of lines.
-*/
 void Fl_Device::begin_loop() {n = 0; what = LOOP;}
 
-/**
-  Starts drawing a convex filled polygon.
-*/
 void Fl_Device::begin_polygon() {n = 0; what = POLYGON;}
 
 /**
@@ -201,10 +189,6 @@ static void fl_transformed_vertex(COORD_T x, COORD_T y) {
   }
 }
 
-/**
-  Adds coordinate pair to the vertex list without further transformations.
-  \param[in] xf,yf transformed coordinate
-*/
 void Fl_Device::transformed_vertex(double xf, double yf) {
 #ifdef __APPLE_QUARTZ__
   fl_transformed_vertex(COORD_T(xf), COORD_T(yf));
@@ -213,17 +197,10 @@ void Fl_Device::transformed_vertex(double xf, double yf) {
 #endif
 }
 
-/**
-  Adds a single vertex to the current path.
-  \param[in] x,y coordinate
-*/
 void Fl_Device::vertex(double x,double y) {
   fl_transformed_vertex(x*m.a + y*m.c + m.x, x*m.b + y*m.d + m.y);
 }
 
-/**
-  Ends list of points, and draws.
-*/
 void Fl_Device::end_points() {
 #if defined(USE_X11)
   if (n>1) XDrawPoints(fl_display, fl_window, fl_gc, p, n, 0);
@@ -250,9 +227,6 @@ void Fl_Device::end_points() {
 #endif
 }
 
-/**
-  Ends list of lines, and draws.
-*/
 void Fl_Device::end_line() {
   if (n < 2) {
     fl_end_points();
@@ -283,18 +257,12 @@ static void fixloop() {  // remove equal points from closed path
   while (n>2 && p[n-1].x == p[0].x && p[n-1].y == p[0].y) n--;
 }
 
-/**
-  Ends closed sequence of lines, and draws.
-*/
 void Fl_Device::end_loop() {
   fixloop();
   if (n>2) fl_transformed_vertex((COORD_T)p[0].x, (COORD_T)p[0].y);
   fl_end_line();
 }
 
-/**
-  Ends convex filled polygon, and draws.
-*/
 void Fl_Device::end_polygon() {
   fixloop();
   if (n < 3) {
@@ -332,20 +300,6 @@ static int counts[20];
 static int numcount;
 #endif
 
-/**
-  Starts drawing a complex filled polygon.
-
-  The polygon may be concave, may have holes in it, or may be several
-  disconnected pieces. Call fl_gap() to separate loops of the path.
-
-  To outline the polygon, use fl_begin_loop() and replace each fl_gap()
-  with fl_end_loop();fl_begin_loop() pairs.
-
-  \note
-  For portability, you should only draw polygons that appear the same
-  whether "even/odd" or "non-zero" winding rules are used to fill them.
-  Holes should be drawn in the opposite direction to the outside loop.
-*/
 void Fl_Device::begin_complex_polygon() {
   fl_begin_polygon();
   gap_ = 0;
@@ -354,12 +308,6 @@ void Fl_Device::begin_complex_polygon() {
 #endif
 }
 
-/**
-  Call fl_gap() to separate loops of the path.
-
-  It is unnecessary but harmless to call fl_gap() before the first vertex,
-  after the last vertex, or several times in a row.
-*/
 void Fl_Device::gap() {
   while (n>gap_+2 && p[n-1].x == p[gap_].x && p[n-1].y == p[gap_].y) n--;
   if (n > gap_+2) {
@@ -373,9 +321,6 @@ void Fl_Device::gap() {
   }
 }
 
-/**
-  Ends complex filled polygon, and draws.
-*/
 void Fl_Device::end_complex_polygon() {
   fl_gap();
   if (n < 3) {
@@ -411,13 +356,6 @@ void Fl_Device::end_complex_polygon() {
 // warning: these do not draw rotated ellipses correctly!
 // See fl_arc.c for portable version.
 
-/**
-  fl_circle() is equivalent to fl_arc(x,y,r,0,360), but may be faster.
-
-  It must be the \e only thing in the path: if you want a circle as part of
-  a complex polygon you must use fl_arc()
-  \param[in] x,y,r center and radius of circle
-*/
 void Fl_Device::circle(double x, double y,double r) {
   double xt = fl_transform_x(x,y);
   double yt = fl_transform_y(x,y);