Corrected duplicated paragraph in previous commit.

Much prefer the \a syntax rather than the \p syntax as it has the same look that the parameters shown in the function declaration (italic).
Should be added to the todo list how to.
Completed all other parameters applying the \a modification in this file. 


git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6323 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
This commit is contained in:
Fabien Costantini
2008-09-21 00:09:12 +00:00
parent 9c187dfcac
commit 87c649e153
+79 -91
View File
@@ -211,12 +211,6 @@ void Fl_Text_Buffer::text(const char *t) {
}
/**
Return a copy of the text between "start" and "end" character positions
from text buffer "buf". Positions start at 0, and the range does not
include the character pointed to by "end".
- - -
Return a copy of the text between \a start and \a end character positions
from text buffer \a buf. Positions start at 0, and the range does not
include the character pointed to by \a end.
@@ -268,7 +262,7 @@ char Fl_Text_Buffer::character(int pos) {
return mBuf[ pos + mGapEnd - mGapStart ];
}
/** Inserts null-terminated string "s" at position "pos". */
/** Inserts null-terminated string \a s at position \a pos. */
void Fl_Text_Buffer::insert(int pos, const char *s) {
int nInserted;
@@ -286,8 +280,8 @@ void Fl_Text_Buffer::insert(int pos, const char *s) {
}
/**
DeleteS the characters between "start" and "end", and inserts the
null-terminated string "s" in their place in the buffer.
Deletes the characters between \a start and \a end, and inserts the
null-terminated string \a s in their place in the buffer.
*/
void Fl_Text_Buffer::replace(int start, int end, const char *s) {
const char * deletedText;
@@ -415,12 +409,12 @@ void Fl_Text_Buffer::canUndo(char flag) {
}
/**
Insert "text" columnwise into buffer starting at displayed character
position "column" on the line beginning at "startPos". Opens a rectangular
space the width and height of "text", by moving all text to the right of
"column" right. If charsInserted and charsDeleted are not NULL, the
Insert \a s columnwise into buffer starting at displayed character
position \a column on the line beginning at \a startPos". Opens a rectangular
space the width and height of \a s, by moving all text to the right of
\a column right. If \a charsInserted and \a charsDeleted are not NULL, the
number of characters inserted and deleted in the operation (beginning
at startPos) are returned in these arguments
at \a startPos) are returned in these arguments.
*/
void Fl_Text_Buffer::insert_column(int column, int startPos, const char *s,
int *charsInserted, int *charsDeleted) {
@@ -446,10 +440,10 @@ void Fl_Text_Buffer::insert_column(int column, int startPos, const char *s,
}
/**
Overlay "text" between displayed character positions "rectStart" and
"rectEnd" on the line beginning at "startPos". If charsInserted and
charsDeleted are not NULL, the number of characters inserted and deleted
in the operation (beginning at startPos) are returned in these arguments.
Overlay \a text between displayed character positions \a rectStart and
\a rectEnd on the line beginning at \a startPos. If \a charsInserted and
\a charsDeleted are not NULL, the number of characters inserted and deleted
in the operation (beginning at \a startPos) are returned in these arguments.
*/
void Fl_Text_Buffer::overlay_rectangular(int startPos, int rectStart,
int rectEnd, const char *s, int *charsInserted, int *charsDeleted) {
@@ -882,7 +876,8 @@ void Fl_Text_Buffer::add_predelete_callback(Fl_Text_Predelete_Cb bufPreDeleteCB,
mPredeleteProcs = newPreDeleteProcs;
mPredeleteCbArgs = newCBArgs;
}
/** Removes a callback routine "bufPreDeleteCB" to be called before text is deleted from the buffer. */
/** Removes a callback routine \a bufPreDeleteCB associated with argument \a cbArg
to be called before text is deleted from the buffer. */
void Fl_Text_Buffer::remove_predelete_callback(
Fl_Text_Predelete_Cb bufPreDeleteCB, void *cbArg) {
int i, toRemove = -1;
@@ -940,14 +935,14 @@ char * Fl_Text_Buffer::line_text(int pos) {
return text_range(line_start(pos), line_end(pos));
}
/** Returns the position of the start of the line containing position "pos". */
/** Returns the position of the start of the line containing position \a pos. */
int Fl_Text_Buffer::line_start(int pos) {
if (!findchar_backward(pos, '\n', &pos))
return 0;
return pos + 1;
}
/** Finds and returns the position of the end of the line containing position "pos"
/** Finds and returns the position of the end of the line containing position \a pos
(which is either a pointer to the newline character ending the line,
or a pointer to one character beyond the end of the buffer)
*/
@@ -978,8 +973,8 @@ int Fl_Text_Buffer::word_end(int pos) {
other control characters are given special treatment.
Get a character from the text buffer expanded into its screen
representation (which may be several characters for a tab or a
control code). Returns the number of characters written to "outStr".
"indent" is the number of characters from the start of the line
control code). Returns the number of characters written to \a outStr.
\a indent is the number of characters from the start of the line
for figuring tabs. Output string is guranteed to be shorter or
equal in length to FL_TEXT_MAX_EXP_CHAR_LEN
*/
@@ -1003,13 +998,14 @@ int Fl_Text_Buffer::expand_character(int pos, int indent, char *outStr) {
}
/**
Expand a single character from the text buffer into it's displayable screen
representation (which may be several characters for a tab or a
control code). Returns the number of characters added to "outStr".
"indent" is the number of characters from the start of the line
for figuring tabs. Output string is guranteed to be shorter or
equal in length to FL_TEXT_MAX_EXP_CHAR_LEN
Expand a single character \a c from the text buffer into it's displayable
screen representation (which may be several characters for a tab or a
control code). Returns the number of characters added to \a outStr.
\a indent is the number of characters from the start of the line
for figuring tabs of length \a tabDist. Output string is guaranteed
to be shorter or equal in length to FL_TEXT_MAX_EXP_CHAR_LEN
Tabs and other control characters are given special treatment.
\a nulSubsChar represent the null character to be transformed in \<nul\>
*/
int Fl_Text_Buffer::expand_character(char c, int indent, char *outStr, int tabDist,
char nullSubsChar) {
@@ -1047,8 +1043,8 @@ int Fl_Text_Buffer::expand_character(char c, int indent, char *outStr, int tabDi
}
/**
Return the length in displayed characters of character "c" expanded
for display (as discussed above in BufGetExpandedChar). If the
Return the length in displayed characters of character \a c expanded
for display (as discussed above in expand_character() ). If the
buffer for which the character width is being measured is doing null
substitution, nullSubsChar should be passed as that character (or nul
to ignore).
@@ -1071,16 +1067,12 @@ int Fl_Text_Buffer::character_width(char c, int indent, int tabDist, char nullSu
return 1;
}
/*
/**
Count the number of displayed characters between buffer position
"lineStartPos" and "targetPos". (displayed characters are the characters
\a lineStartPos and \a targetPos. (displayed characters are the characters
shown on the screen to represent characters in the buffer, where tabs and
control characters are expanded)
*/
/**
Determines the number of characters that will be displayed
between lineStartPos and targetPos.
*/
int Fl_Text_Buffer::count_displayed_characters(int lineStartPos, int targetPos) {
int pos, charCount = 0;
char expandedChar[ FL_TEXT_MAX_EXP_CHAR_LEN ];
@@ -1092,7 +1084,7 @@ int Fl_Text_Buffer::count_displayed_characters(int lineStartPos, int targetPos)
}
/**
Count forward from buffer position "startPos" in displayed characters
Count forward from buffer position \a startPos in displayed characters
(displayed characters are the characters shown on the screen to represent
characters in the buffer, where tabs and control characters are expanded)
*/
@@ -1112,8 +1104,8 @@ int Fl_Text_Buffer::skip_displayed_characters(int lineStartPos, int nChars) {
}
/**
Counts the number of newlines between startPos and endPos in buffer "buf".
The character at position "endPos" is not counted.
Counts the number of newlines between \a startPos and \a endPos in buffer.
The character at position \a endPos is not counted.
*/
int Fl_Text_Buffer::count_lines(int startPos, int endPos) {
int pos, gapLen = mGapEnd - mGapStart;
@@ -1135,13 +1127,9 @@ int Fl_Text_Buffer::count_lines(int startPos, int endPos) {
return lineCount;
}
/*
Find the first character of the line "nLines" forward from "startPos"
in "buf" and return its position
*/
/**
Returns the buffer position for the Nth line after the start
position.
Finds the first character of the line \a nLines forward from \a startPos
in the buffer and returns its position
*/
int Fl_Text_Buffer::skip_lines(int startPos, int nLines) {
int pos, gapLen = mGapEnd - mGapStart;
@@ -1169,9 +1157,9 @@ int Fl_Text_Buffer::skip_lines(int startPos, int nLines) {
}
/**
Finds and returns the position of the first character of the line "nLines" backwards
from "startPos" (not counting the character pointed to by "startpos" if
that is a newline) in "buf". nLines == 0 means find the beginning of the line
Finds and returns the position of the first character of the line \a nLines backwards
from \a startPos (not counting the character pointed to by \a startpos if
that is a newline) in the buffer. \a nLines == 0 means find the beginning of the line
*/
int Fl_Text_Buffer::rewind_lines(int startPos, int nLines) {
int pos, gapLen = mGapEnd - mGapStart;
@@ -1199,8 +1187,8 @@ int Fl_Text_Buffer::rewind_lines(int startPos, int nLines) {
}
/**
Search forwards in buffer for string "searchString", starting with the
character "startPos", and returning the result in "foundPos"
Search forwards in buffer for string \a searchString, starting with the
character \a startPos, and returning the result in \a foundPos
returns 1 if found, 0 if not.
*/
int Fl_Text_Buffer::search_forward(int startPos, const char *searchString,
@@ -1224,7 +1212,7 @@ int Fl_Text_Buffer::search_forward(int startPos, const char *searchString,
/**
Search backwards in buffer for string <i>searchCharssearchString</i>, starting with the
character BEFORE "startPos", returning the result in "foundPos"
character BEFORE \a startPos, returning the result in \a foundPos
returns 1 if found, 0 if not.
*/
int Fl_Text_Buffer::search_backward(int startPos, const char *searchString,
@@ -1248,8 +1236,8 @@ int Fl_Text_Buffer::search_backward(int startPos, const char *searchString,
/**
Finds the next occurrence of the specified characters.
Search forwards in buffer for characters in <i>searchChars</i>, starting
with the character <i>startPos</i>, and returning the result in <i>foundPos</i>
Search forwards in buffer for characters in \a searchChars, starting
with the character \a startPos, and returning the result in \a foundPos
returns 1 if found, 0 if not.
*/
int Fl_Text_Buffer::findchars_forward(int startPos, const char *searchChars,
@@ -1282,8 +1270,8 @@ int Fl_Text_Buffer::findchars_forward(int startPos, const char *searchChars,
/**
Finds the previous occurrence of the specified characters.
Search backwards in buffer for characters in "searchChars", starting
with the character BEFORE "startPos", returning the result in "foundPos"
Search backwards in buffer for characters in \a searchChars, starting
with the character BEFORE \a startPos, returning the result in \a foundPos
returns 1 if found, 0 if not.
*/
int Fl_Text_Buffer::findchars_backward(int startPos, const char *searchChars,
@@ -1529,9 +1517,9 @@ void Fl_Text_Buffer::remove_(int start, int end) {
/**
Inserts a column of text without calling the modify callbacks. Note that
in some pathological cases, inserting can actually decrease the size of
the buffer because of spaces being coalesced into tabs. "nDeleted" and
"nInserted" return the number of characters deleted and inserted beginning
at the start of the line containing "startPos". "endPos" returns buffer
the buffer because of spaces being coalesced into tabs. \a nDeleted and
\a nInserted return the number of characters deleted and inserted beginning
at the start of the line containing \a startPos. \a endPos returns buffer
position of the lower left edge of the inserted column (as a hint for
routines which need to set a cursor position).
*/
@@ -1614,7 +1602,7 @@ void Fl_Text_Buffer::insert_column_(int column, int startPos, const char *insTex
Deletes a rectangle of text without calling the modify callbacks. Returns
the number of characters replacing those between start and end. Note that
in some pathological cases, deleting can actually increase the size of
the buffer because of tab expansions. "endPos" returns the buffer position
the buffer because of tab expansions. \a endPos returns the buffer position
of the point in the last line where the text was removed (as a hint for
routines which need to position the cursor after a delete operation)
*/
@@ -1666,9 +1654,9 @@ void Fl_Text_Buffer::remove_rectangular_(int start, int end, int rectStart,
/**
Overlay a rectangular area of text without calling the modify callbacks.
"nDeleted" and "nInserted" return the number of characters deleted and
inserted beginning at the start of the line containing "startPos".
"endPos" returns buffer position of the lower left edge of the inserted
\a nDeleted and \a nInserted return the number of characters deleted and
inserted beginning at the start of the line containing \a startPos.
\a endPos returns buffer position of the lower left edge of the inserted
column (as a hint for routines which need to set a cursor position).
*/
void Fl_Text_Buffer::overlay_rectangular_(int startPos, int rectStart,
@@ -1738,9 +1726,9 @@ void Fl_Text_Buffer::overlay_rectangular_(int startPos, int rectStart,
}
/**
Inserts characters from single-line string "insLine" in single-line string
"line" at "column", leaving "insWidth" space before continuing line.
"outLen" returns the number of characters written to "outStr", "endOffset"
Inserts characters from single-line string \a insLine in single-line string
\a line at \a column, leaving \a insWidth space before continuing line.
\a outLen returns the number of characters written to \a outStr, \a endOffset
returns the number of characters from the beginning of the string to
the right edge of the inserted text (as a hint for routines which need
to position the cursor).
@@ -1827,11 +1815,11 @@ static void insertColInLine(const char *line, char *insLine, int column, int ins
}
/**
Removes characters in single-line string "line" between displayed positions
"rectStart" and "rectEnd", and write the result to "outStr", which is
Removes characters in single-line string \a line between displayed positions
\a rectStart and \a rectEnd, and write the result to \a outStr, which is
assumed to be large enough to hold the returned string. Note that in
certain cases, it is possible for the string to get longer due to
expansion of tabs. "endOffset" returns the number of characters from
expansion of tabs. \a endOffset returns the number of characters from
the beginning of the string to the point where the characters were
deleted (as a hint for routines which need to position the cursor).
*/
@@ -1887,9 +1875,9 @@ static void deleteRectFromLine(const char *line, int rectStart, int rectEnd,
}
/**
Overlay characters from single-line string "insLine" on single-line string
"line" between displayed character offsets "rectStart" and "rectEnd".
"outLen" returns the number of characters written to "outStr", "endOffset"
Overlay characters from single-line string \a insLine on single-line string
\a line between displayed character offsets \a rectStart and \a rectEnd.
\a outLen returns the number of characters written to \a outStr, \a endOffset
returns the number of characters from the beginning of the string to
the right edge of the inserted text (as a hint for routines which need
to position the cursor).
@@ -2026,7 +2014,7 @@ int Fl_Text_Selection::position(int *startpos, int *endpos,
}
/**
Return true if position "pos" with indentation "dispIndex" is in
Return true if position \a pos with indentation \a dispIndex is in
the Fl_Text_Selection.
*/
int Fl_Text_Selection::includes(int pos, int lineStartPos, int dispIndex) {
@@ -2056,7 +2044,7 @@ char * Fl_Text_Buffer::selection_text_(Fl_Text_Selection *sel) {
else
return text_range(start, end);
}
/** Removes the text from the buffer corresponding to "sel".*/
/** Removes the text from the buffer corresponding to \a sel.*/
void Fl_Text_Buffer::remove_selection_(Fl_Text_Selection *sel) {
int start, end;
int isRect, rectStart, rectEnd;
@@ -2221,8 +2209,8 @@ void Fl_Text_Buffer::move_gap(int pos) {
}
/**
Reallocates the text storage in "buf" to have a gap starting at "newGapStart"
and a gap size of "newGapLen", preserving the buffer's current contents.
Reallocates the text storage in the buffer to have a gap starting at \a newGapStart
and a gap size of \a newGapLen, preserving the buffer's current contents.
*/
void Fl_Text_Buffer::reallocate_with_gap(int newGapStart, int newGapLen) {
char * newBuf;
@@ -2254,7 +2242,7 @@ void Fl_Text_Buffer::reallocate_with_gap(int newGapStart, int newGapLen) {
}
/**
Update all of the selections in "buf" for changes in the buffer's text
Updates all of the selections in the buffer for changes in the buffer's text
*/
void Fl_Text_Buffer::update_selections(int pos, int nDeleted,
int nInserted) {
@@ -2264,7 +2252,7 @@ void Fl_Text_Buffer::update_selections(int pos, int nDeleted,
}
/**
Update an individual selection for changes in the corresponding text
Updates an individual selection for changes in the corresponding text
*/
void Fl_Text_Selection::update(int pos, int nDeleted,
int nInserted) {
@@ -2289,8 +2277,8 @@ void Fl_Text_Selection::update(int pos, int nDeleted,
/**
Finds the next occurrence of the specified character.
Search forwards in buffer for character "searchChar", starting
with the character "startPos", and returning the result in "foundPos"
Search forwards in buffer for character \a searchChar, starting
with the character \a startPos, and returning the result in \a foundPos
returns 1 if found, 0 if not. (The difference between this and
BufSearchForward is that it's optimized for single characters. The
overall performance of the text widget is dependent on its ability to
@@ -2325,8 +2313,8 @@ int Fl_Text_Buffer::findchar_forward(int startPos, char searchChar,
}
/**
Search backwards in buffer "buf" for character "searchChar", starting
with the character BEFORE "startPos", returning the result in "foundPos"
Search backwards in buffer \a buf for character \a searchChar, starting
with the character BEFORE \a startPos, returning the result in \a foundPos
returns 1 if found, 0 if not. (The difference between this and
BufSearchBackward is that it's optimized for single characters. The
overall performance of the text widget is dependent on its ability to
@@ -2360,9 +2348,9 @@ int Fl_Text_Buffer::findchar_backward(int startPos, char searchChar,
}
/*
Copy from "text" to end up to but not including newline (or end of "text")
Copies from \a text to end up to but not including newline (or end of \a text)
and return the copy as the function value, and the length of the line in
"lineLen"
\a lineLen
*/
static char *copyLine(const char *text, int *lineLen) {
int len = 0;
@@ -2378,7 +2366,7 @@ static char *copyLine(const char *text, int *lineLen) {
}
/*
Count the number of newlines in a null-terminated text string;
Counts the number of newlines in a null-terminated text string;
*/
static int countLines(const char *string) {
const char * c;
@@ -2390,7 +2378,7 @@ static int countLines(const char *string) {
}
/*
Measure the width in displayed characters of string "text"
Measures the width in displayed characters of string \a text
*/
static int textWidth(const char *text, int tabDist, char nullSubsChar) {
int width = 0, maxWidth = 0;
@@ -2410,7 +2398,7 @@ static int textWidth(const char *text, int tabDist, char nullSubsChar) {
}
/**
Find the first and last character position in a line within a rectangular
Finds the first and last character position in a line within a rectangular
selection (for copying). Includes tabs which cross rectStart, but not
control characters which do so. Leaves off tabs which cross rectEnd.
@@ -2462,9 +2450,9 @@ void Fl_Text_Buffer::rectangular_selection_boundaries(int lineStartPos,
}
/*
Adjust the space and tab characters from string "text" so that non-white
Adjust the space and tab characters from string \a text so that non-white
characters remain stationary when the text is shifted from starting at
"origIndent" to starting at "newIndent". Returns an allocated string
\a origIndent to starting at \a newIndent. Returns an allocated string
which must be freed by the caller with XtFree.
*/
static char *realignTabs(const char *text, int origIndent, int newIndent,
@@ -2495,8 +2483,8 @@ static char *realignTabs(const char *text, int origIndent, int newIndent,
/*
Expand tabs to spaces for a block of text. The additional parameter
"startIndent" if nonzero, indicates that the text is a rectangular selection
beginning at column "startIndent"
\a startIndent if nonzero, indicates that the text is a rectangular selection
beginning at column \a startIndent
*/
static char *expandTabs(const char *text, int startIndent, int tabDist,
char nullSubsChar, int *newLen) {