fix for doxygen warnings

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@56084 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

interface/wx/arrstr.h

@@ -96,13 +96,10 @@ public:
     size_t Add(const wxString& str, size_t copies = 1);
 
     /**
-        Preallocates enough memory to store @a nCount items. This function may be
+        Preallocates enough memory to store @a nCount items.
-        used to improve array class performance before adding a known number of items
-        consecutively.
 
-        @todo FIX THIS LINK
+        This function may be used to improve array class performance before
-
+        adding a known number of items consecutively.
-        @see @ref wxArray::memorymanagement "Dynamic array memory management"
     */
     void Alloc(size_t nCount);
 
@@ -186,13 +183,10 @@ public:
     void RemoveAt(size_t nIndex, size_t count = 1);
 
     /**
-        Releases the extra memory allocated by the array. This function is useful to
+        Releases the extra memory allocated by the array.
-        minimize the array memory consumption.
+        This function is useful to minimize the array memory consumption.
 
-        @todo FIX THIS LINK
+        @see Alloc()
-
-        @see Alloc(), @ref wxArray::memorymanagement "Dynamic array memory
-        management"
     */
     void Shrink();
 

interface/wx/cmdproc.h

@@ -219,13 +219,16 @@ public:
     void SetUndoAccelerator(const wxString& accel);
 
     /**
-        Submits a new command to the command processor. The command processor
+        Submits a new command to the command processor.
-        calls wxCommand::Do() to execute the command; if it succeeds, the
-        command is stored in the history list, and the associated edit menu (if
-        any) updated appropriately. If it fails, the command is deleted
-        immediately. Once Submit() has been called, the passed command should
-        not be deleted directly by the application.
 
+        The command processor calls wxCommand::Do() to execute the command;
+        if it succeeds, the command is stored in the history list, and the
+        associated edit menu (if any) updated appropriately.
+        If it fails, the command is deleted immediately. Once Submit() has been
+        called, the passed command should not be deleted directly by the application.
+
+        @param command
+            The command to submit
         @param storeIt
             Indicates whether the successful command should be stored in the
             history list.

interface/wx/cmndata.h

@@ -418,6 +418,8 @@ public:
         @param i
             An integer between 0 and 15 for whatever custom colour you want to
             set. The default custom colours are invalid colours.
+        @param colour
+            The colour to set
     */
     void SetCustomColour(int i, const wxColour& colour);
 

interface/wx/config.h

@@ -329,7 +329,8 @@ public:
                  const wxString& vendorName = wxEmptyString,
                  const wxString& localFilename = wxEmptyString,
                  const wxString& globalFilename = wxEmptyString,
-                 long style = 0);
+                 long style = 0,
+                 const wxMBConv& conv = wxConvAuto());
 
     /**
         Empty but ensures that dtor of all derived classes is virtual.

interface/wx/ctrlsub.h

@@ -73,7 +73,7 @@ public:
         @param string
             The label to set.
     */
-    virtual void SetString(unsigned int n, const wxString& s);
+    virtual void SetString(unsigned int n, const wxString& string);
 
     /**
         Finds an item whose label matches the given string.
@@ -86,7 +86,7 @@ public:
         @return The zero-based position of the item, or wxNOT_FOUND if the
                 string was not found.
     */
-    virtual int FindString(const wxString& s, bool bCase = false) const;
+    virtual int FindString(const wxString& string, bool caseSensitive = false) const;
 
     //@}
 

interface/wx/cursor.h

@@ -130,10 +130,9 @@ public:
 
         @param cursorName
             The name of the resource or the image file to load.
-
         @param type
             Icon type to load. It defaults to wxCURSOR_DEFAULT_TYPE,
-            which is a #define associated to different values on different
+            which is a @#define associated to different values on different
             platforms:
             - under Windows, it defaults to wxBITMAP_TYPE_CUR_RESOURCE.
             - under MacOS, it defaults to wxBITMAP_TYPE_MACCURSOR_RESOURCE.

interface/wx/datstrm.h

@@ -28,14 +28,14 @@ class wxDataOutputStream
 {
 public:
     /**
-        Constructs a datastream object from an output stream. Only write
+        Constructs a datastream object from an output stream.
-        methods will be available.
+        Only write methods will be available.
 
         @param stream
             The output stream.
     */
-    wxDataOutputStream(wxOutputStream& s,
+    wxDataOutputStream(wxOutputStream& stream);
-                       const wxMBConv& conv = wxConvAuto(wxFONTENCODING_DEFAULT));
+
     /**
         Constructs a datastream object from an output stream. Only write
         methods will be available. This constructor is only available in
@@ -173,14 +173,14 @@ class wxDataInputStream
 {
 public:
     /**
-        Constructs a datastream object from an input stream. Only read methods
+        Constructs a datastream object from an input stream.
-        will be available.
+        Only read methods will be available.
 
         @param stream
             The input stream.
     */
-    wxDataInputStream(wxInputStream& s,
+    wxDataInputStream(wxInputStream& stream);
-                      const wxMBConv& conv = wxConvAuto(wxFONTENCODING_DEFAULT));
+
     /**
         Constructs a datastream object from an input stream. Only read methods
         will be available. This constructor is only available in Unicode builds

interface/wx/debug.h

@@ -22,9 +22,8 @@
 #define wxASSERT( condition )
 
 /**
-    This macro results in a
+    This macro results in a @ref wxCOMPILE_TIME_ASSERT "compile time assertion failure"
-    @ref overview_wxcompiletimeassert "compile time assertion failure" if the
+    if the size of the given @c type is less than @c size bits.
-    size of the given @c type is less than @c size bits.
 
     You may use it like this, for example:
 
@@ -41,8 +40,8 @@
 #define wxASSERT_MIN_BITSIZE( type, size )
 
 /**
-    Assert macro with message. An error message will be generated if the
+    Assert macro with message.
-    condition is @false.
+    An error message will be generated if the condition is @false.
 
     @see wxASSERT(), wxCOMPILE_TIME_ASSERT()
 
@@ -52,8 +51,7 @@
 
 /**
     Checks that the condition is @true, returns with the given return value if
-    not (stops execution in debug mode). This check is done even in release
+    not (stops execution in debug mode). This check is done even in release mode.
-    mode.
 
     @header{wx/debug.h}
 */
@@ -61,8 +59,7 @@
 
 /**
     Checks that the condition is @true, returns with the given return value if
-    not (stops execution in debug mode). This check is done even in release
+    not (stops execution in debug mode). This check is done even in release mode.
-    mode.
 
     This macro may be only used in non-void functions, see also wxCHECK_RET().
 

interface/wx/display.h

@@ -27,7 +27,7 @@ public:
             The index of the display to use. This must be non-negative and
             lower than the value returned by GetCount().
     */
-    wxDisplay(unsigned int n = 0);
+    wxDisplay(unsigned int index = 0);
 
     /**
         Destructor.

interface/wx/dnd.h

@@ -205,12 +205,17 @@ public:
                  const wxIconOrCursor& iconCopy = wxNullIconOrCursor,
                  const wxIconOrCursor& iconMove = wxNullIconOrCursor,
                  const wxIconOrCursor& iconNone = wxNullIconOrCursor);
+
     /**
+        The constructor for wxDataObject.
+
         Note that the exact type of @a iconCopy and subsequent parameters
         differs between wxMSW and wxGTK: these are cursors under Windows but
         icons for GTK. You should use the macro wxDROP_ICON() in portable
         programs instead of directly using either of these types.
 
+        @param data
+            The data associated with the drop source.
         @param win
             The window which initiates the drag and drop operation.
         @param iconCopy
@@ -260,8 +265,6 @@ public:
         @param effect
             The effect to implement. One of ::wxDragCopy, ::wxDragMove,
             ::wxDragLink and ::wxDragNone.
-        @param scrolling
-            @true if the window is scrolling. MSW only.
 
         @return @false if you want default feedback, or @true if you implement
                 your own feedback. The return value is ignored under GTK.

interface/wx/dynarray.h

@@ -224,10 +224,12 @@ public:
         Default constructor.
     */
     wxArray();
+
     /**
         Default constructor initializes an empty array object.
     */
     wxObjArray();
+
     /**
         There is no default constructor for wxSortedArray classes - you must
         initialize it with a function to use for item comparison. It is a
@@ -243,11 +245,13 @@ public:
         even if the source array contains the items of pointer type).
     */
     wxArray(const wxArray& array);
+
     /**
         Performs a shallow array copy (i.e. doesn't copy the objects pointed to
         even if the source array contains the items of pointer type).
     */
     wxSortedArray(const wxSortedArray& array);
+
     /**
         Performs a deep copy (i.e. the array element are copied too).
     */
@@ -258,11 +262,13 @@ public:
         even if the source array contains the items of pointer type).
     */
     wxArray& operator=(const wxArray& array);
+
     /**
         Performs a shallow array copy (i.e. doesn't copy the objects pointed to
         even if the source array contains the items of pointer type).
     */
     wxSortedArray& operator=(const wxSortedArray& array);
+
     /**
         Performs a deep copy (i.e. the array element are copied too).
     */
@@ -273,11 +279,13 @@ public:
         may use the WX_CLEAR_ARRAY() macro for this.
     */
     ~wxArray();
+
     /**
         This destructor does not delete all the items owned by the array, you
         may use the WX_CLEAR_ARRAY() macro for this.
     */
     ~wxSortedArray();
+
     /**
         This destructor deletes all the items owned by the array.
     */
@@ -384,6 +392,7 @@ public:
         a lot of items.
     */
     void Add(T item, size_t copies = 1);
+
     /**
         Appends the @a item to the array consisting of the elements of type
         @c T.
@@ -392,6 +401,7 @@ public:
         @a item is stored.
     */
     size_t Add(T item);
+
     /**
         Appends the @a item to the array consisting of the elements of type
         @c T.
@@ -407,6 +417,7 @@ public:
         a lot of items.
     */
     void Add(T* item);
+
     /**
         Appends the given number of @a copies of the @a item to the array
         consisting of the elements of type @c T.
@@ -445,6 +456,7 @@ public:
         overloaded versions of this function.
     */
     void Insert(T item, size_t n, size_t copies = 1);
+
     /**
         Insert the @a item into the array before the existing item @a n - thus,
         @e Insert(something, 0u) will insert an item in such way that it will
@@ -457,6 +469,7 @@ public:
         overloaded versions of this function.
     */
     void Insert(T* item, size_t n);
+
     /**
         Insert the given number of @a copies of the @a item into the array
         before the existing item @a n - thus, @e Insert(something, 0u) will

interface/wx/filectrl.h

@@ -60,12 +60,12 @@ public:
         @param id
             The identifier for the control.
         @param defaultDirectory
-            The initial directory shown in the control. Must be
+            The initial directory shown in the control.
-            a valid path to a directory or the empty string.
+            Must be a valid path to a directory or the empty string.
             In case it is the empty string, the current working directory is used.
         @param defaultFilename
             The default filename, or the empty string.
-        @param wildcard
+        @param wildCard
             A wildcard specifying which files can be selected,
             such as "*.*" or "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif".
         @param style

interface/wx/filedlg.h

@@ -96,7 +96,7 @@ public:
                  const wxString& wildcard = ".",
                  long style = wxFD_DEFAULT_STYLE,
                  const wxPoint& pos = wxDefaultPosition,
-                 const wxSize& sz = wxDefaultSize,
+                 const wxSize& size = wxDefaultSize,
                  const wxString& name = "filedlg");
 
     /**

interface/wx/filename.h

@@ -53,10 +53,12 @@ wxULongLong wxInvalidSize;
 /**
     @class wxFileName
 
-    wxFileName encapsulates a file name. This class serves two purposes: first, it
+    wxFileName encapsulates a file name.
-    provides the functions to split the file names into components and to recombine
+
-    these components in the full file name which can then be passed to the OS file
+    This class serves two purposes: first, it provides the functions to split the
-    functions (and @ref overview_filefunctions "wxWidgets functions" wrapping them).
+    file names into components and to recombine these components in the full file
+    name which can then be passed to the OS file functions
+    (and @ref group_funcmacro_file "wxWidgets functions" wrapping them).
     Second, it includes the functions for working with the files itself. Note that
     to change the file data you should use wxFile class instead.
     wxFileName provides functions for working with the file attributes.
@@ -812,7 +814,7 @@ public:
         In other words, it returns the file name which should be used to access
         this file if the current directory were pathBase.
 
-        @param pathBase.
+        @param pathBase
             The directory to use as root, current directory is used by default
         @param format
             The file name format, native by default
@@ -847,7 +849,7 @@ public:
 
         @param dir
             The directory to create
-        @param parm
+        @param perm
             The permissions for the newly created directory.
             See the ::wxPosixPermissions enumeration for more info.
         @param flags

interface/wx/filesys.h

@@ -224,10 +224,14 @@ public:
             not be empty in this case).
         @param anchor
             Anchor. See GetAnchor() for details.
+        @param modif
+            Modification date and time for this file.
     */
-    wxFSFile(wxInputStream stream, const wxString& loc,
+    wxFSFile(wxInputStream stream,
+             const wxString& location,
              const wxString& mimetype,
-             const wxString& anchor, wxDateTime modif);
+             const wxString& anchor,
+             wxDateTime modif);
 
     /**
         Detaches the stream from the wxFSFile object. That is, the

interface/wx/slider.h

@@ -9,8 +9,8 @@
 /**
     @class wxSlider
 
-    A slider is a control with a handle which can be pulled
+    A slider is a control with a handle which can be pulled back and forth to
-    back and forth to change the value.
+    change the value.
 
     On Windows, the track bar control is used.
 
@@ -40,6 +40,71 @@
            compatible with wxSL_SELRANGE.
     @endStyleTable
 
+    @beginEventTable{wxScrollEvent}
+    You can use EVT_COMMAND_SCROLL... macros with window IDs for when intercepting
+    scroll events from controls, or EVT_SCROLL... macros without window IDs for
+    intercepting scroll events from the receiving window -- except for this,
+    the macros behave exactly the same.
+    @event{EVT_SCROLL(func)}
+        Process all scroll events.
+    @event{EVT_SCROLL_TOP(func)}
+        Process wxEVT_SCROLL_TOP scroll-to-top events (minimum position).
+    @event{EVT_SCROLL_BOTTOM(func)}
+        Process wxEVT_SCROLL_BOTTOM scroll-to-bottom events (maximum position).
+    @event{EVT_SCROLL_LINEUP(func)}
+        Process wxEVT_SCROLL_LINEUP line up events.
+    @event{EVT_SCROLL_LINEDOWN(func)}
+        Process wxEVT_SCROLL_LINEDOWN line down events.
+    @event{EVT_SCROLL_PAGEUP(func)}
+        Process wxEVT_SCROLL_PAGEUP page up events.
+    @event{EVT_SCROLL_PAGEDOWN(func)}
+        Process wxEVT_SCROLL_PAGEDOWN page down events.
+    @event{EVT_SCROLL_THUMBTRACK(func)}
+        Process wxEVT_SCROLL_THUMBTRACK thumbtrack events
+        (frequent events sent as the user drags the thumbtrack).
+    @event{EVT_SCROLL_THUMBRELEASE(func)}
+        Process wxEVT_SCROLL_THUMBRELEASE thumb release events.
+    @event{EVT_SCROLL_CHANGED(func)}
+        Process wxEVT_SCROLL_CHANGED end of scrolling events (MSW only).
+    @event{EVT_COMMAND_SCROLL(id, func)}
+        Process all scroll events.
+    @event{EVT_COMMAND_SCROLL_TOP(id, func)}
+        Process wxEVT_SCROLL_TOP scroll-to-top events (minimum position).
+    @event{EVT_COMMAND_SCROLL_BOTTOM(id, func)}
+        Process wxEVT_SCROLL_BOTTOM scroll-to-bottom events (maximum position).
+    @event{EVT_COMMAND_SCROLL_LINEUP(id, func)}
+        Process wxEVT_SCROLL_LINEUP line up events.
+    @event{EVT_COMMAND_SCROLL_LINEDOWN(id, func)}
+        Process wxEVT_SCROLL_LINEDOWN line down events.
+    @event{EVT_COMMAND_SCROLL_PAGEUP(id, func)}
+        Process wxEVT_SCROLL_PAGEUP page up events.
+    @event{EVT_COMMAND_SCROLL_PAGEDOWN(id, func)}
+        Process wxEVT_SCROLL_PAGEDOWN page down events.
+    @event{EVT_COMMAND_SCROLL_THUMBTRACK(id, func)}
+        Process wxEVT_SCROLL_THUMBTRACK thumbtrack events
+        (frequent events sent as the user drags the thumbtrack).
+    @event{EVT_COMMAND_SCROLL_THUMBRELEASE(func)}
+        Process wxEVT_SCROLL_THUMBRELEASE thumb release events.
+    @event{EVT_COMMAND_SCROLL_CHANGED(func)}
+        Process wxEVT_SCROLL_CHANGED end of scrolling events (MSW only).
+    @endEventTable
+
+    @section slider_diff The difference between EVT_SCROLL_THUMBRELEASE and EVT_SCROLL_CHANGED
+
+    The EVT_SCROLL_THUMBRELEASE event is only emitted when actually dragging the
+    thumb using the mouse and releasing it (This EVT_SCROLL_THUMBRELEASE event
+    is also followed by an EVT_SCROLL_CHANGED event).
+
+    The EVT_SCROLL_CHANGED event also occurs when using the keyboard to change
+    the thumb position, and when clicking next to the thumb
+    (In all these cases the EVT_SCROLL_THUMBRELEASE event does not happen).
+    In short, the EVT_SCROLL_CHANGED event is triggered when scrolling/ moving
+    has finished independently of the way it had started.
+    Please see the widgets sample ("Slider" page) to see the difference between
+    EVT_SCROLL_THUMBRELEASE and EVT_SCROLL_CHANGED in action.
+
+    @todo are all strings "Windows 95 only" really up2date?
+
     @library{wxcore}
     @category{ctrl}
     <!-- @appearance{slider.png} -->
@@ -68,8 +133,7 @@ public:
         @param maxValue
             Maximum slider position.
         @param size
-            Window size. If wxDefaultSize is specified then a default size
+            Window size. If wxDefaultSize is specified then a default size is chosen.
-        is chosen.
         @param style
             Window style. See wxSlider.
         @param validator
@@ -107,8 +171,8 @@ public:
     virtual void ClearTicks();
 
     /**
-        Used for two-step slider construction. See wxSlider()
+        Used for two-step slider construction.
-        for further details.
+        See wxSlider() for further details.
     */
     bool Create(wxWindow* parent, wxWindowID id, int value,
                 int minValue, int maxValue,
@@ -193,8 +257,8 @@ public:
         Sets the line size for the slider.
 
         @param lineSize
-            The number of steps the slider moves when the user moves it up or down a
+            The number of steps the slider moves when the user moves it up
-        line.
+            or down a line.
 
         @see GetLineSize()
     */
@@ -260,10 +324,9 @@ public:
 
         @param n
             Frequency. For example, if the frequency is set to two, a tick mark is
-        displayed for
+            displayed for every other increment in the slider's range.
-            every other increment in the slider's range.
         @param pos
-            Position. Must be greater than zero. TODO: what is this for?
+            Position. Must be greater than zero. @todo: what is this for?
 
         @remarks Windows 95 only.
 

interface/wx/window.h

@@ -319,7 +319,7 @@ public:
 
         @remarks This function is currently only implemented under Mac/Carbon.
     */
-    virtual void AlwaysShowScrollbars(bool = true, bool = true);
+    virtual void AlwaysShowScrollbars(bool hflag = true, bool vflag = true);
 
     /**
         Sets the cached best size value.
@@ -839,16 +839,12 @@ public:
     //@{
     /**
         Returns the size of the window 'client area' in pixels.
+
         The client area is the area which may be drawn on by the programmer,
         excluding title bar, border, scrollbars, etc.
         Note that if this window is a top-level one and it is currently minimized, the
         return size is empty (both width and height are 0).
 
-        @param width
-            Receives the client width in pixels.
-        @param height
-            Receives the client height in pixels.
-
         @see GetSize(), GetVirtualSize()
     */
     void GetClientSize(int* width, int* height) const;
@@ -1255,7 +1251,12 @@ public:
     /**
         This gets the virtual size of the window in pixels.
         By default it returns the client size of the window, but after a call to
-        SetVirtualSize() it will return that size.
+        SetVirtualSize() it will return the size set with that method.
+    */
+    wxSize GetVirtualSize() const;
+
+    /**
+        Like the other GetVirtualSize() overload but uses pointers instead.
 
         @param width
             Receives the window virtual width.
@@ -1263,7 +1264,6 @@ public:
             Receives the window virtual height.
     */
     void GetVirtualSize(int* width, int* height) const;
-    wxSize GetVirtualSize() const;
     //@}
 
     /**
@@ -1688,14 +1688,10 @@ public:
         processed as usually. If the coordinates are not specified, current mouse
         cursor position is used.
 
-        @param menu
+        @a menu is the menu to pop up.
-            Menu to pop up.
+
-        @param pos
+        The position where the menu will appear can be specified either as a
-            The position where the menu will appear.
+        wxPoint @a pos or by two integers (@a x and @a y).
-        @param x
-            Required x position for the menu to appear.
-        @param y
-            Required y position for the menu to appear.
 
         @remarks Just before the menu is popped up, wxMenu::UpdateUI is called to
                  ensure that the menu items are in the correct state.
@@ -1863,7 +1859,6 @@ public:
     */
     virtual bool Reparent(wxWindow* newParent);
 
-    //@{
     /**
         Converts from screen to client window coordinates.
 
@@ -1871,12 +1866,16 @@ public:
             Stores the screen x coordinate and receives the client x coordinate.
         @param y
             Stores the screen x coordinate and receives the client x coordinate.
-        @param pt
-            The screen position for the second form of the function.
     */
     virtual void ScreenToClient(int* x, int* y) const;
+
+    /**
+        Converts from screen to client window coordinates.
+
+        @param pt
+            The screen position.
+    */
     virtual wxPoint ScreenToClient(const wxPoint& pt) const;
-    //@}
 
     /**
         Scrolls the window by the given number of lines down (if @a lines is
@@ -2050,13 +2049,6 @@ public:
         than SetSize(), since the application need not worry about what dimensions
         the border or title bar have when trying to fit the window around panel
         items, for example.
-
-        @param width
-            The required client area width.
-        @param height
-            The required client area height.
-        @param size
-            The required client size.
     */
     virtual void SetClientSize(int width, int height);
     virtual void SetClientSize(const wxSize& size);

interface/wx/xrc/xmlres.h

@@ -39,7 +39,6 @@ enum wxXmlResourceFlags
 class wxXmlResource : public wxObject
 {
 public:
-    //@{
     /**
         Constructor.
 
@@ -56,9 +55,19 @@ public:
     wxXmlResource(const wxString& filemask,
                   int flags = wxXRC_USE_LOCALE,
                   const wxString domain = wxEmptyString);
+
+    /**
+        Constructor.
+
+        @param flags
+            One or more value of the ::wxXmlResourceFlags enumeration.
+        @param domain
+            The name of the gettext catalog to search for translatable strings.
+            By default all loaded catalogs will be searched.
+            This provides a way to allow the strings to only come from a specific catalog.
+    */
     wxXmlResource(int flags = wxXRC_USE_LOCALE,
                   const wxString domain = wxEmptyString);
-    //@}
 
     /**
         Destructor.