More initial reviews of d* interface headers.

[wxWidgets.git] / interface / dcscreen.h

diff --git a/interface/dcscreen.h b/interface/dcscreen.h
index 7c4854c7ea66bb203ddab07ee616df49eda1e79e..80e4c9ec66abde82ec661e9bb52b2539e4615f82 100644 (file)
--- a/interface/dcscreen.h
+++ b/interface/dcscreen.h
@@ -1,6 +1,6 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        dcscreen.h
-// Purpose:     documentation for wxScreenDC class
+// Purpose:     interface of wxScreenDC
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
@@ -10,15 +10,13 @@
     @class wxScreenDC
     @wxheader{dcscreen.h}
 
-    A wxScreenDC can be used to paint on the screen.
-    This should normally be constructed as a temporary stack object; don't store
-    a wxScreenDC object.
+    A wxScreenDC can be used to paint on the screen. This should normally be
+    constructed as a temporary stack object; don't store a wxScreenDC object.
 
     @library{wxcore}
     @category{dc}
 
-    @seealso
-    wxDC, wxMemoryDC, wxPaintDC, wxClientDC, wxWindowDC
+    @see wxDC, wxMemoryDC, wxPaintDC, wxClientDC, wxWindowDC
 */
 class wxScreenDC : public wxDC
 {
@@ -30,38 +28,56 @@ public:
 
     /**
         Use this in conjunction with StartDrawingOnTop().
-        This function destroys the temporary window created to implement on-top drawing
-        (X only).
+
+        This function destroys the temporary window created to implement on-top
+        drawing (X only).
     */
     bool EndDrawingOnTop();
 
-    //@{
     /**
-        Use this in conjunction with EndDrawingOnTop() to
-        ensure that drawing to the screen occurs on top of existing windows. Without
-        this,
-        some window systems (such as X) only allow drawing to take place underneath
+        Use this in conjunction with EndDrawingOnTop() to ensure that drawing
+        to the screen occurs on top of existing windows. Without this, some
+        window systems (such as X) only allow drawing to take place underneath
         other windows.
-        By using the first form of this function, an application is specifying that
-        the area that will be drawn on coincides with the given window.
-        By using the second form, an application can specify an area of the screen
-        which is to be drawn on. If @NULL is passed, the whole screen is available.
-        It is recommended that an area of the screen is specified because with large
-        regions,
-        flickering effects are noticeable when destroying the temporary transparent
-        window used
-        to implement this feature.
-        You might use this pair of functions when implementing a drag feature, for
-        example
-        as in the wxSplitterWindow implementation.
-        
+
+        This version of StartDrawingOnTop() is used to specify that the area
+        that will be drawn on coincides with the given window. It is
+        recommended that an area of the screen is specified with
+        StartDrawingOnTop(wxRect*) because with large regions, flickering
+        effects are noticeable when destroying the temporary transparent window
+        used to implement this feature.
+
+        You might use this function when implementing a drag feature, for
+        example as in the wxSplitterWindow implementation.
+
         @remarks This function is probably obsolete since the X implementations
-                 allow drawing directly on the screen now. However, the
-                 fact that this function allows the screen to be
-                 refreshed afterwards, may be useful to some
-                 applications.
+                 allow drawing directly on the screen now. However, the fact
+                 that this function allows the screen to be refreshed
+                 afterwards, may be useful to some applications.
     */
     bool StartDrawingOnTop(wxWindow* window);
+    /**
+        Use this in conjunction with EndDrawingOnTop() to ensure that drawing
+        to the screen occurs on top of existing windows. Without this, some
+        window systems (such as X) only allow drawing to take place underneath
+        other windows.
+
+        This version of StartDrawingOnTop() is used to specify an area of the
+        screen which is to be drawn on. If @NULL is passed, the whole screen is
+        available. It is recommended that an area of the screen is specified
+        with this function rather than with StartDrawingOnTop(wxWindow*),
+        because with large regions, flickering effects are noticeable when
+        destroying the temporary transparent window used to implement this
+        feature.
+
+        You might use this function when implementing a drag feature, for
+        example as in the wxSplitterWindow implementation.
+
+        @remarks This function is probably obsolete since the X implementations
+                 allow drawing directly on the screen now. However, the fact
+                 that this function allows the screen to be refreshed
+                 afterwards, may be useful to some applications.
+    */
     bool StartDrawingOnTop(wxRect* rect = NULL);
-    //@}
 };
+