Fix premature truncation of brief descriptions in Doxygen comments.

Don't end the brief description at the first period if it's a period which is
part of "i.e." or "e.g.": escape the space following it to prevent Doxygen
from recognizing it as an end of sentence.

See #14866.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@73084 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Vadim Zeitlin
2012-12-01 00:14:07 +00:00
parent faadbe6f39
commit 0824e36969
41 changed files with 82 additions and 83 deletions

View File

@@ -173,7 +173,7 @@ public:
void TransformPoint(wxDouble* x, wxDouble* y) const;
/**
Applies the linear part of this matrix, i.e. without translation.
Applies the linear part of this matrix, i.e.\ without translation.
@param p
The source receiving the transformations.

View File

@@ -185,7 +185,7 @@ public:
void TransformPoint(wxDouble* x, wxDouble* y) const;
/**
Applies the linear part of this matrix, i.e. without translation.
Applies the linear part of this matrix, i.e.\ without translation.
@param p
The source receiving the transformations.

View File

@@ -94,7 +94,7 @@ public:
virtual int FilterEvent(wxEvent& event);
/**
Returns the main event loop instance, i.e. the event loop which is started
Returns the main event loop instance, i.e.\ the event loop which is started
by OnRun() and which dispatches all events sent from the native toolkit
to the application (except when new event loops are temporarily set-up).
The returned value maybe @NULL. Put initialization code which needs a
@@ -245,7 +245,7 @@ public:
static wxAppConsole* GetInstance();
/**
Returns @true if the main event loop is currently running, i.e. if the
Returns @true if the main event loop is currently running, i.e.\ if the
application is inside OnRun().
This can be useful to test whether events can be dispatched. For example,
@@ -260,7 +260,7 @@ public:
//@{
/**
This function is called when an assert failure occurs, i.e. the condition
This function is called when an assert failure occurs, i.e.\ the condition
specified in wxASSERT() macro evaluated to @false.
It is only called in debug mode (when @c __WXDEBUG__ is defined) as
@@ -288,7 +288,7 @@ public:
const wxChar *msg);
/**
Called when command line parsing fails (i.e. an incorrect command line option
Called when command line parsing fails (i.e.\ an incorrect command line option
was specified by the user). The default behaviour is to show the program usage
text and abort the program.
@@ -700,7 +700,7 @@ public:
virtual wxWindow* GetTopWindow() const;
/**
Returns @true if the application is active, i.e. if one of its windows is
Returns @true if the application is active, i.e.\ if one of its windows is
currently in the foreground.
If this function returns @false and you need to attract users attention to

View File

@@ -178,7 +178,7 @@ public:
wxCharTypeBuffer(const wxScopedCharTypeBuffer<T>& src);
/**
Assigns @a str to this buffer and takes ownership of it (i.e. the
Assigns @a str to this buffer and takes ownership of it (i.e.\ the
buffer becomes "owned").
*/
wxCharTypeBuffer& operator=(const CharType *str);

View File

@@ -145,7 +145,7 @@ public:
bool HasBackgroundColour() const;
/**
Returns @true if a non-default (i.e. any) border is set.
Returns @true if a non-default (i.e.\ any) border is set.
*/
bool HasBorder() const;

View File

@@ -259,7 +259,7 @@ public:
bool HasValue(const wxDataViewItem& item, unsigned col) const;
/**
Override this to indicate of @a item is a container, i.e. if
Override this to indicate of @a item is a container, i.e.\ if
it can have child items.
*/
virtual bool IsContainer(const wxDataViewItem& item) const = 0;

View File

@@ -754,7 +754,7 @@ public:
/**
Returns @true if the date is equal to another one up to the given time
interval, i.e. if the absolute difference between the two dates is less
interval, i.e.\ if the absolute difference between the two dates is less
than this interval.
*/
bool IsEqualUpTo(const wxDateTime& dt, const wxTimeSpan& ts) const;
@@ -1214,7 +1214,7 @@ public:
WeekFlags flags = Monday_First);
/**
Sets the date to the day number @a yday in the same year (i.e., unlike
Sets the date to the day number @a yday in the same year (i.e.\ unlike
the other functions, this one does not use the current year). The day
number should be in the range 1-366 for the leap years and 1-365 for
the other ones.
@@ -1339,7 +1339,7 @@ public:
/**
Converts the year in absolute notation (i.e. a number which can be
Converts the year in absolute notation (i.e.\ a number which can be
negative, positive or zero) to the year in BC/AD notation. For the
positive years, nothing is done, but the year 0 is year 1 BC and so for
other years there is a difference of 1.
@@ -1381,7 +1381,7 @@ public:
Country country = Country_Default);
/**
Get the current century, i.e. first two digits of the year, in given
Get the current century, i.e.\ first two digits of the year, in given
calendar (only Gregorian is currently supported).
*/
static int GetCentury(int year);
@@ -1567,7 +1567,7 @@ public:
/**
Returns the object corresponding to the midnight of the current day
(i.e. the same as Now(), but the time part is set to 0).
(i.e.\ the same as Now(), but the time part is set to 0).
@see Now()
*/
@@ -2016,7 +2016,7 @@ public:
bool IsEqualTo(const wxTimeSpan& ts) const;
/**
Compares two timespans: works with the absolute values, i.e. -2 hours
Compares two timespans: works with the absolute values, i.e.\ -2 hours
is longer than 1 hour. Also, it will return @false if the timespans are
equal in absolute value.
*/
@@ -2038,7 +2038,7 @@ public:
bool IsPositive() const;
/**
Compares two timespans: works with the absolute values, i.e. 1 hour is
Compares two timespans: works with the absolute values, i.e.\ 1 hour is
shorter than -2 hours. Also, it will return @false if the timespans are
equal in absolute value.
*/

View File

@@ -73,7 +73,7 @@ enum wxMappingMode
wxMM_TWIPS,
/**
Each logical unit is a @e "printer point" i.e. 1/72 of an inch.
Each logical unit is a @e "printer point" i.e.\ 1/72 of an inch.
Equivalent to about 353 micrometers.
*/
wxMM_POINTS
@@ -1413,7 +1413,7 @@ public:
bool IsOk() const;
/**
Sets the x and y axis orientation (i.e., the direction from lowest to
Sets the x and y axis orientation (i.e.\ the direction from lowest to
highest values on the axis). The default orientation is x axis from
left to right and y axis from top down.
@@ -1427,7 +1427,7 @@ public:
void SetAxisOrientation(bool xLeftRight, bool yBottomUp);
/**
Sets the device origin (i.e., the origin in pixels after scaling has
Sets the device origin (i.e.\ the origin in pixels after scaling has
been applied). This function may be useful in Windows printing
operations for placing a graphic on a page.
*/

View File

@@ -119,7 +119,7 @@ public:
virtual bool HangUp() = 0;
/**
Returns @true if the computer has a permanent network connection (i.e.
Returns @true if the computer has a permanent network connection (i.e.\
is on a LAN) and so there is no need to use Dial() function to go
online.

View File

@@ -254,36 +254,36 @@ public:
wxSortedArray(int (*)(T first, T second)compareFunction);
/**
Performs a shallow array copy (i.e. doesn't copy the objects pointed to
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).
*/
wxArray(const wxArray& array);
/**
Performs a shallow array copy (i.e. doesn't copy the objects pointed to
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).
Performs a deep copy (i.e.\ the array element are copied too).
*/
wxObjArray(const wxObjArray& array);
/**
Performs a shallow array copy (i.e. doesn't copy the objects pointed to
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).
*/
wxArray& operator=(const wxArray& array);
/**
Performs a shallow array copy (i.e. doesn't copy the objects pointed to
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).
Performs a deep copy (i.e.\ the array element are copied too).
*/
wxObjArray& operator=(const wxObjArray& array);
@@ -376,7 +376,7 @@ public:
T& Item(size_t index) const;
/**
Returns the last element in the array, i.e. is the same as calling
Returns the last element in the array, i.e.\ is the same as calling
"Item(GetCount() - 1)". An assert failure is raised in the debug mode
if the array is empty.

View File

@@ -37,19 +37,19 @@ public:
bool GetAddress(void* addr, size_t* len) const;
/**
Returns the base name of this module, e.g. @c "kernel32.dll" or
Returns the base name of this module, e.g.\ @c "kernel32.dll" or
@c "libc-2.3.2.so".
*/
wxString GetName() const;
/**
Returns the full path of this module if available, e.g.
@c "c:\windows\system32\kernel32.dll" or @c "/lib/libc-2.3.2.so".
Returns the full path of this module if available, e.g.\ @c "c:\windows\system32\kernel32.dll"
or @c "/lib/libc-2.3.2.so".
*/
wxString GetPath() const;
/**
Returns the version of this module, e.g. @c "5.2.3790.0" or @c "2.3.2".
Returns the version of this module, e.g.\ @c "5.2.3790.0" or @c "2.3.2".
The returned string is empty if the version information is not
available.
*/
@@ -138,7 +138,7 @@ public:
wxPluginCategory cat = wxDL_PLUGIN_GUI);
/**
Detaches this object from its library handle, i.e. the object will not
Detaches this object from its library handle, i.e.\ the object will not
unload the library any longer in its destructor but it is now the
callers responsibility to do this using Unload().
*/

View File

@@ -224,7 +224,7 @@ public:
void SetTimestamp(long timeStamp = 0);
/**
Test if this event should be propagated or not, i.e. if the propagation level
Test if this event should be propagated or not, i.e.\ if the propagation level
is currently greater than 0.
*/
bool ShouldPropagate() const;
@@ -2726,7 +2726,7 @@ public:
int GetLinesPerAction() const;
/**
Returns the logical mouse position in pixels (i.e. translated according to the
Returns the logical mouse position in pixels (i.e.\ translated according to the
translation set for the DC, which usually indicates that the window has been
scrolled).
*/

View File

@@ -118,7 +118,7 @@ public:
const wxString& name = wxFileCtrlNameStr);
/**
Returns the current directory of the file control (i.e. the directory shown by it).
Returns the current directory of the file control (i.e.\ the directory shown by it).
*/
virtual wxString GetDirectory() const;

View File

@@ -322,7 +322,7 @@ wxString wxPathOnly(const wxString& path);
bool wxIsWild(const wxString& pattern);
/**
Returns @true if the argument is an absolute filename, i.e. with a slash
Returns @true if the argument is an absolute filename, i.e.\ with a slash
or drive name at the beginning.
@header{wx/filefn.h}

View File

@@ -954,9 +954,8 @@ public:
void Set(int width, int height);
/**
Combine this size object with another one replacing the default (i.e.
equal to -1) components of this object with those of the other. It is
typically used like this:
Combine this size object with another one replacing the default (i.e.\ equal to -1)
components of this object with those of the other. It is typically used like this:
@code
if ( !size.IsFullySpecified() )

View File

@@ -30,7 +30,7 @@ class wxIconLocation
{
public:
/**
Returns @true if the object is valid, i.e. was properly initialized, and
Returns @true if the object is valid, i.e.\ was properly initialized, and
@false otherwise.
*/
bool IsOk() const;

View File

@@ -1356,7 +1356,7 @@ public:
bool IsOk() const;
/**
Returns @true if the given pixel is transparent, i.e. either has the mask
Returns @true if the given pixel is transparent, i.e.\ either has the mask
colour if this image has a mask or if this image has alpha channel and alpha
value of this pixel is strictly less than @a threshold.
*/

View File

@@ -902,7 +902,7 @@ public:
bool IsEnabled(int id) const;
/**
Inserts the given @a item at position 0, i.e. before all the other
Inserts the given @a item at position 0, i.e.\ before all the other
existing items.
@see Append(), Insert()
@@ -910,7 +910,7 @@ public:
wxMenuItem* Prepend(wxMenuItem* item);
/**
Inserts the given @a item at position 0, i.e. before all the other
Inserts the given @a item at position 0, i.e.\ before all the other
existing items.
@see Append(), Insert()

View File

@@ -262,7 +262,7 @@ public:
virtual wxClassInfo* GetClassInfo() const;
/**
Returns the wxObject::m_refData pointer, i.e. the data referenced by this object.
Returns the wxObject::m_refData pointer, i.e.\ the data referenced by this object.
@see Ref(), UnRef(), wxObject::m_refData, SetRefData(), wxObjectRefData
*/

View File

@@ -106,7 +106,7 @@ public:
int GetTextCtrlProportion() const;
/**
Returns @true if this window has a valid text control (i.e. if the @c
Returns @true if this window has a valid text control (i.e.\ if the @c
wxPB_USE_TEXTCTRL style was given when creating this control).
*/
bool HasTextCtrl() const;

View File

@@ -38,7 +38,7 @@ public:
bool Create(wxWindow *parent, int flags = wxBORDER_NONE);
/**
Move the popup window to the right position, i.e. such that it is
Move the popup window to the right position, i.e.\ such that it is
entirely visible.
The popup is positioned at ptOrigin + size if it opens below and to the

View File

@@ -163,7 +163,7 @@ public:
wxString GetMatch(const wxString& text, size_t index = 0) const;
/**
Returns the size of the array of matches, i.e. the number of bracketed
Returns the size of the array of matches, i.e.\ the number of bracketed
subexpressions plus one for the expression itself, or 0 on error.
May only be called after successful call to Compile().

View File

@@ -322,7 +322,7 @@ public:
virtual bool IsEmpty() const;
/**
Returns @true if the region is equal to, i.e. covers the same area as,
Returns @true if the region is equal to, i.e.\ covers the same area as,
another one.
If both this region and @a region are both invalid, they are considered

View File

@@ -43,7 +43,7 @@ enum
/** Mouse is currently over the control. */
wxCONTROL_CURRENT = 0x00000010,
/** Selected item in e.g. listbox. */
/** Selected item in e.g.\ listbox. */
wxCONTROL_SELECTED = 0x00000020,
/** (Check/radio button) is checked. */

View File

@@ -642,7 +642,7 @@ public:
bool IsShown(size_t index) const;
/**
Call this to force layout of the children anew, e.g. after having added a child
Call this to force layout of the children anew, e.g.\ after having added a child
to or removed a child (window, other sizer or space) from the sizer while
keeping the current dimension.
*/

View File

@@ -115,7 +115,7 @@ public:
virtual wxString GetConfigDir() const;
/**
Return the location of the applications global, i.e. not user-specific,
Return the location of the applications global, i.e.\ not user-specific,
data files.
Example return values:
@@ -159,7 +159,7 @@ public:
virtual wxString GetExecutablePath() const;
/**
Return the program installation prefix, e.g. @c /usr, @c /opt or @c /home/zeitlin.
Return the program installation prefix, e.g.\ @c /usr, @c /opt or @c /home/zeitlin.
If the prefix had been previously by SetInstallPrefix(), returns that
value, otherwise tries to determine it automatically (Linux only right now)

View File

@@ -1092,7 +1092,7 @@ public:
/**
Gets the thread identifier: this is a platform dependent number that uniquely
identifies the thread throughout the system during its existence
(i.e. the thread identifiers may be reused).
(i.e.\ the thread identifiers may be reused).
*/
wxThreadIdType GetId() const;
@@ -1123,7 +1123,7 @@ public:
unsigned int GetPriority() const;
/**
Returns @true if the thread is alive (i.e. started and not terminating).
Returns @true if the thread is alive (i.e.\ started and not terminating).
Note that this function can only safely be used with joinable threads, not
detached ones as the latter delete themselves and so when the real thread is

View File

@@ -86,7 +86,7 @@ public:
wxEvtHandler* GetOwner() const;
/**
Returns @true if the timer is one shot, i.e. if it will stop after firing
Returns @true if the timer is one shot, i.e.\ if it will stop after firing
the first notification automatically.
*/
bool IsOneShot() const;

View File

@@ -37,7 +37,7 @@ public:
virtual ~wxTipProvider();
/**
Returns the index of the current tip (i.e. the one which would be returned by GetTip()).
Returns the index of the current tip (i.e.\ the one which would be returned by GetTip()).
The program usually remembers the value returned by this function after calling
wxShowTip(). Note that it is not the same as the value which was passed to

View File

@@ -136,7 +136,7 @@ public:
wxString GetNextToken();
/**
Returns the current position (i.e. one index after the last returned
Returns the current position (i.e.\ one index after the last returned
token or 0 if GetNextToken() has never been called) in the original
string.
*/

View File

@@ -319,7 +319,7 @@ public:
wxObject* clientData = NULL);
/**
Adds any control to the toolbar, typically e.g. a wxComboBox.
Adds any control to the toolbar, typically e.g.\ a wxComboBox.
@param control
The control to be added.

View File

@@ -214,7 +214,7 @@ public:
virtual void Iconize(bool iconize = true);
/**
Returns @true if this window is currently active, i.e. if the user is
Returns @true if this window is currently active, i.e.\ if the user is
currently working with it.
*/
virtual bool IsActive();

View File

@@ -726,7 +726,7 @@ public:
virtual bool IsBold(const wxTreeItemId& item) const;
/**
Returns @true if the control is empty (i.e. has no items, even no root
Returns @true if the control is empty (i.e.\ has no items, even no root
one).
*/
bool IsEmpty() const;

View File

@@ -54,7 +54,7 @@ public:
value_type GetValue() const;
/**
Returns true if the character is an ASCII character (i.e. if its value is less than 128).
Returns true if the character is an ASCII character (i.e.\ if its value is less than 128).
*/
bool IsAscii() const;

View File

@@ -97,7 +97,7 @@ public:
wxProtocol& GetProtocol();
/**
Returns @true if this object is correctly initialized, i.e. if
Returns @true if this object is correctly initialized, i.e.\ if
GetError() returns ::wxURL_NOERR.
*/
bool IsOk() const;

View File

@@ -112,7 +112,7 @@ public:
/**
Returns vector's current capacity, i.e. how much memory is allocated.
Returns vector's current capacity, i.e.\ how much memory is allocated.
@see reserve()
*/

View File

@@ -35,17 +35,17 @@ public:
bool Matches(const wxVideoMode& other) const;
/**
Returns the screen width in pixels (e.g. 640), 0 means unspecified.
Returns the screen width in pixels (e.g.\ 640), 0 means unspecified.
*/
int GetWidth() const;
/**
Returns the screen height in pixels (e.g. 480), 0 means unspecified.
Returns the screen height in pixels (e.g.\ 480), 0 means unspecified.
*/
int GetHeight() const;
/**
Returns bits per pixel (e.g. 32), 1 is monochrome and 0 means
Returns bits per pixel (e.g.\ 32), 1 is monochrome and 0 means
unspecified/known.
*/
int GetDepth() const;
@@ -62,17 +62,17 @@ public:
/**
The screen width in pixels (e.g. 640), 0 means unspecified.
The screen width in pixels (e.g.\ 640), 0 means unspecified.
*/
int w;
/**
The screen height in pixels (e.g. 480), 0 means unspecified.
The screen height in pixels (e.g.\ 480), 0 means unspecified.
*/
int h;
/**
Bits per pixel (e.g. 32), 1 is monochrome and 0 means
Bits per pixel (e.g.\ 32), 1 is monochrome and 0 means
unspecified/known.
*/
int bpp;

View File

@@ -190,7 +190,7 @@ public:
bool IsSelected(size_t item) const;
/**
Selects or deselects the specified item which must be valid (i.e. not
Selects or deselects the specified item which must be valid (i.e.\ not
equal to @c wxNOT_FOUND).
@return @true if the items selection status has changed or @false
@@ -270,7 +270,7 @@ public:
void SetSelectionBackground(const wxColour& col);
/**
Toggles the state of the specified @a item, i.e. selects it if it was
Toggles the state of the specified @a item, i.e.\ selects it if it was
unselected and deselects it if it was selected.
This method is only valid for multi selection listboxes.

View File

@@ -372,7 +372,7 @@ public:
virtual wxString GetPageText() const = 0;
/**
Returns whether the web control is currently busy (e.g. loading a page).
Returns whether the web control is currently busy (e.g.\ loading a page).
*/
virtual bool IsBusy() const = 0;

View File

@@ -339,8 +339,8 @@ public:
/**
This method may be overridden in the derived classes to return @false to
indicate that this control doesn't accept input at all (i.e. behaves like
e.g. wxStaticText) and so doesn't need focus.
indicate that this control doesn't accept input at all (i.e.\ behaves like
e.g.\ wxStaticText) and so doesn't need focus.
@see AcceptsFocusFromKeyboard()
*/
@@ -535,7 +535,7 @@ public:
bool IsDescendant(wxWindowBase* win) const;
/**
Reparents the window, i.e. the window will be removed from its
Reparents the window, i.e.\ the window will be removed from its
current parent window (e.g. a non-standard toolbar in a wxFrame)
and then re-inserted into another.
@@ -1401,7 +1401,7 @@ public:
virtual wxPoint GetClientAreaOrigin() const;
/**
Get the client rectangle in window (i.e. client) coordinates
Get the client rectangle in window (i.e.\ client) coordinates
*/
wxRect GetClientRect() const;
@@ -2364,7 +2364,7 @@ public:
virtual bool HideWithEffect(wxShowEffect effect,
unsigned int timeout = 0);
/**
Returns @true if the window is enabled, i.e. if it accepts user input,
Returns @true if the window is enabled, i.e.\ if it accepts user input,
@false otherwise.
Notice that this method can return @false even if this window itself hadn't
@@ -2404,7 +2404,7 @@ public:
virtual bool IsShown() const;
/**
Returns @true if the window is physically visible on the screen, i.e. it
Returns @true if the window is physically visible on the screen, i.e.\ it
is shown and all its parents up to the toplevel window are shown as well.
@see IsShown()
@@ -3223,7 +3223,7 @@ public:
virtual void InitDialog();
/**
Returns @true if the window contents is double-buffered by the system, i.e. if
Returns @true if the window contents is double-buffered by the system, i.e.\ if
any drawing done on the window is really done on a temporary backing surface
and transferred to the screen all at once later.
@@ -3245,7 +3245,7 @@ public:
/**
Returns @true if this window is intrinsically enabled, @false otherwise,
i.e. if @ref Enable() Enable(@false) had been called. This method is
i.e.\ if @ref Enable() Enable(@false) had been called. This method is
mostly used for wxWidgets itself, user code should normally use
IsEnabled() instead.
*/
@@ -3599,7 +3599,7 @@ protected:
virtual int DoGetBestClientWidth(int height) const;
/**
Sets the initial window size if none is given (i.e. at least one of the
Sets the initial window size if none is given (i.e.\ at least one of the
components of the size passed to ctor/Create() is wxDefaultCoord).
@deprecated Use SetInitialSize() instead.
*/

View File

@@ -82,7 +82,7 @@ public:
static wxXLocale& GetCLocale();
/**
Returns @true if this object is initialized, i.e. represents a valid locale
Returns @true if this object is initialized, i.e.\ represents a valid locale
or @false otherwise.
*/
bool IsOk() const;