Completed and corrected Fl and related Fl_Window documentation, added cross references, especially to back compatibility functions to the new ones.

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

3 files changed, 16 insertions, 19 deletions

diff --git a/src/Fl.cxx b/src/Fl.cxx
index 5006ea143..050abe510 100644
--- a/src/Fl.cxx
+++ b/src/Fl.cxx
@@ -754,7 +754,7 @@ void Fl::focus(Fl_Widget *o) {
 static char dnd_flag = 0; // make 'belowmouse' send DND_LEAVE instead of LEAVE
 
 /**
-    Get or set the widget that is below the mouse.  This is for
+    Sets the widget that is below the mouse.  This is for
     highlighting buttons.  It is not used to send FL_PUSH or 
     FL_MOVE directly, for several obscure reasons, but those events
     typically go to this widget.  This is also the first widget tried for 
@@ -782,7 +782,7 @@ void Fl::belowmouse(Fl_Widget *o) {
 }
 
 /**
-    Get or set the widget that is being pushed. FL_DRAG or 
+    Sets the widget that is being pushed. FL_DRAG or 
     FL_RELEASE (and any more FL_PUSH) events will be sent to
     this widget.
     
@@ -1291,8 +1291,7 @@ int Fl_Window::handle(int ev)
 ////////////////////////////////////////////////////////////////
 // Back compatibility cut & paste functions for fltk 1.1 only:
 
-/**
-    The single-argument selection_owner(x) call can be used to
+/** Back-compatibility only: The single-argument call can be used to
     move the selection to another widget or to set the owner to
     NULL, without changing the actual text of the
     selection. FL_SELECTIONCLEAR is sent to the previous
@@ -1318,7 +1317,7 @@ void Fl::selection(Fl_Widget &owner, const char* text, int len) {
   Fl::copy(text, len, 0);
 }
 
-/**
+/** Backward compatibility only:
   Set things up so the receiver widget will be called with an  FL_PASTE event some
   time in the future for the specified clipboard. The reciever
   should be prepared to be called <I>directly</I> by this, or for
@@ -1326,6 +1325,7 @@ void Fl::selection(Fl_Widget &owner, const char* text, int len) {
   allows the window system to take as long as necessary to retrieve
   the paste buffer (or even to screw up completely) without complex
   and error-prone synchronization code in FLTK.
+  \see Fl::paste(Fl_Widget &receiver, int clipboard)
 */
 void Fl::paste(Fl_Widget &receiver) {
   Fl::paste(receiver, 0);
diff --git a/src/Fl_Window.cxx b/src/Fl_Window.cxx
index 32459d367..70b9c7f47 100644
--- a/src/Fl_Window.cxx
+++ b/src/Fl_Window.cxx
@@ -168,17 +168,14 @@ void Fl::default_atclose(Fl_Window* window, void* v) {
   window->hide();
   Fl_Widget::default_callback(window, v); // put on Fl::read_queue()
 }
-
+/** Back compatibility: default window callback handler \see Fl::set_atclose() */
 void (*Fl::atclose)(Fl_Window*, void*) = default_atclose;
-/**
-   Sets the default callback v for win to call on close event.
-   <P> For back compatibility only.
-*/
+/** Back compatibility: Sets the default callback v for win to call on close event */
 void Fl_Window::default_callback(Fl_Window* win, void* v) {
   Fl::atclose(win, v);
 }
 
-/**  Returns the last window that was made current. */
+/**  Returns the last window that was made current. \see Fl_Window::make_current() */
 Fl_Window *Fl_Window::current() {
   return current_;
 }
diff --git a/src/screen_xywh.cxx b/src/screen_xywh.cxx
index bd31be0fd..529e74c4b 100644
--- a/src/screen_xywh.cxx
+++ b/src/screen_xywh.cxx
@@ -151,12 +151,10 @@ int Fl::screen_count() {
 }
 
 /**
-  Gets the bounding box of a screen. The first form gets the
-  bounding box for the screen the mouse pointer is in. The second
-  form gets the bounding box for the screen that contains the
-  specified coordinates. The last form gets the bounding box for
-  the numbered screen, where n is a number from 0 to the
-  number of screens less 1.
+  Gets the bounding box of a screen 
+  where the mouse pointer is in. 
+  \param[out]  X,Y,W,H the corresponding screen bounding box
+  \param[in] mx, my the mouse absolute screen position
 */
 void Fl::screen_xywh(int &X, int &Y, int &W, int &H, int mx, int my) {
   if (!num_screens) screen_init();
@@ -222,8 +220,10 @@ void Fl::screen_xywh(int &X, int &Y, int &W, int &H, int mx, int my) {
 }
 
 /**
-  Returns the screen bounding rect for the given screen. 
-  See void screen_xywh(int &x, int &y, int &w, int &h, int mx, int my) 
+  Gets the screen bounding rect for the given screen. 
+  \param[out]  X,Y,W,H the corresponding screen bounding box
+  \param[in] n the screen number (0 to Fl::screen_count() - 1)
+  \see void screen_xywh(int &x, int &y, int &w, int &h, int mx, int my) 
 */
 void Fl::screen_xywh(int &X, int &Y, int &W, int &H, int n) {
   if (!num_screens) screen_init();