inline docs

From: "Matthias Clasen" <matthiasc poet de>
To: <gtk-devel-list gnome org>
Subject: inline docs
Date: Mon, 24 Sep 2001 09:13:12 +0200
Hi, since I can't conveniently compile CVS currently, I decided to take
a look at the state of the API documentation and started with the Unicode
related stuff in glib. The following patch is an attempt at improving the
consistency of the inline docs, without changing the content.
I'd like to continue looking at the inline docs, if there is interest in
this
kind of change. Some questions:

1) Ok to commit this ?
2) Are you interested in more changes like this ?
3) Should I also move things from templates to doc comments in the c files ?
(I think the consensus is to
    move away from templates and go with inline docs.)
4) Another thing where consistency could be improved is quoting in
externalized messages.
    I've seen `foo', 'foo' and "foo" (there may be more variants). What is
the preferred quoting in
    English text ?

Matthias


Index: ChangeLog
===================================================================
RCS file: /cvs/gnome/glib/ChangeLog,v
retrieving revision 1.846
diff -u -b -B -u -r1.846 ChangeLog
--- ChangeLog 2001/09/22 19:40:56 1.846
+++ ChangeLog 2001/09/23 23:10:50
@@ -1,3 +1,8 @@
+2001-09-23  Matthias Clasen  <matthiasc poet de>
+
+ * glib/gutf8.c, glib/gunibreak.c, glib/gunicollate.c,
+ glib/gunidecomp.c, glib/guniprop.c: Inline doc consistency fixes.
+
 2001-09-22  Hans Breuer  <hans breuer org>

  * glib/giowin32.c : simply setting is_readable and is_writeable
Index: glib/gutf8.c
===================================================================
RCS file: /cvs/gnome/glib/glib/gutf8.c,v
retrieving revision 1.26
diff -u -b -B -u -r1.26 gutf8.c
--- glib/gutf8.c 2001/09/10 15:50:26 1.26
+++ glib/gutf8.c 2001/09/23 23:10:53
@@ -114,14 +114,14 @@

 /**
  * g_utf8_find_prev_char:
- * @str: pointer to the beginning of a UTF-8 string
+ * @str: pointer to the beginning of a UTF-8 encoded string
  * @p: pointer to some position within @str
  *
  * Given a position @p with a UTF-8 encoded string @str, find the start
  * of the previous UTF-8 character starting before @p. Returns %NULL if no
  * UTF-8 characters are present in @p before @str.
  *
- * @p does not have to be at the beginning of a UTF-8 chracter. No check
+ * @p does not have to be at the beginning of a UTF-8 character. No check
  * is made to see if the character found is actually valid other than
  * it starts with an appropriate byte.
  *
@@ -143,12 +143,12 @@
  * g_utf8_find_next_char:
  * @p: a pointer to a position within a UTF-8 encoded string
  * @end: a pointer to the end of the string, or %NULL to indicate
- *        that the string is NULL terminated, in which case
+ *        that the string is nul-terminated, in which case
  *        the returned value will be
  *
- * Find the start of the next utf-8 character in the string after @p
+ * Finds the start of the next UTF-8 character in the string after @p.
  *
- * @p does not have to be at the beginning of a UTF-8 chracter. No check
+ * @p does not have to be at the beginning of a UTF-8 character. No check
  * is made to see if the character found is actually valid other than
  * it starts with an appropriate byte.
  *
@@ -174,12 +174,12 @@
  * g_utf8_prev_char:
  * @p: a pointer to a position within a UTF-8 encoded string
  *
- * Find the previous UTF-8 character in the string before @p.
+ * Finds the previous UTF-8 character in the string before @p.
  *
  * @p does not have to be at the beginning of a UTF-8 character. No check
  * is made to see if the character found is actually valid other than
  * it starts with an appropriate byte. If @p might be the first
- * character of the string, you must use g_utf8_find_prev_char instead.
+ * character of the string, you must use g_utf8_find_prev_char() instead.
  *
  * Return value: a pointer to the found character.
  **/
@@ -196,7 +196,7 @@

 /**
  * g_utf8_strlen:
- * @p: pointer to the start of a UTF-8 string.
+ * @p: pointer to the start of a UTF-8 encoded string.
  * @max: the maximum number of bytes to examine. If @max
  *       is less than 0, then the string is assumed to be
  *       nul-terminated.
@@ -243,12 +243,12 @@

 /**
  * g_utf8_get_char:
- * @p: a pointer to unicode character encoded as UTF-8
+ * @p: a pointer to Unicode character encoded as UTF-8
  *
- * Convert a sequence of bytes encoded as UTF-8 to a unicode character.
+ * Converts a sequence of bytes encoded as UTF-8 to a unicode character.
  * If @p does not point to a valid UTF-8 encoded character, results are
  * undefined. If you are not sure that the bytes are complete
- * valid unicode characters, you should use g_utf8_get_char_validated()
+ * valid Unicode characters, you should use g_utf8_get_char_validated()
  * instead.
  *
  * Return value: the resulting character
@@ -271,7 +271,7 @@
 /**
  * g_utf8_offset_to_pointer:
  * @str: a UTF-8 encoded string
- * @offset: a character offset within the string.
+ * @offset: a character offset within @str
  *
  * Converts from an integer character offset to a pointer to a position
  * within the string.
@@ -295,7 +295,7 @@
  * @pos: a pointer to a position within @str
  *
  * Converts from a pointer to position within a string to a integer
- * character offset
+ * character offset.
  *
  * Return value: the resulting character offset
  **/
@@ -319,7 +319,7 @@
 /**
  * g_utf8_strncpy:
  * @dest: buffer to fill with characters from @src
- * @src: UTF-8 string
+ * @src: UTF-8 encoded string
  * @n: character count
  *
  * Like the standard C strncpy() function, but copies a given number
@@ -440,9 +440,9 @@
  * @c: a ISO10646 character code
  * @outbuf: output buffer, must have at least 6 bytes of space.
  *       If %NULL, the length will be computed and returned
- *       and nothing will be written to @out.
+ *       and nothing will be written to @outbuf.
  *
- * Convert a single character to utf8
+ * Converts a single character to UTF-8.
  *
  * Return value: number of bytes written
  **/
@@ -500,16 +500,17 @@

 /**
  * g_utf8_strchr:
- * @p: a nul-terminated utf-8 string
- * @len: the maximum length of p
- * @c: a iso-10646 character
- *
- * Find the leftmost occurence of the given iso-10646 character
- * in a UTF-8 string, while limiting the search to p_len bytes.
- * If len is -1, allow unbounded search.
- *
- * Return value: NULL if the string does not contain the character,
otherwise, a
- *               a pointer to the start of the leftmost of the character in
the string.
+ * @p: a nul-terminated UTF-8 encoded string
+ * @len: the maximum length of @p
+ * @c: a ISO10646 character
+ *
+ * Finds the leftmost occurrence of the given ISO10646 character
+ * in a UTF-8 encoded string, while limiting the search to @len bytes.
+ * If @len is -1, allow unbounded search.
+ *
+ * Return value: %NULL if the string does not contain the character,
+ *   otherwise, a pointer to the start of the leftmost occurrence of
+ *   the character in the string.
  **/
 gchar *
 g_utf8_strchr (const char *p,
@@ -527,16 +528,17 @@

 /**
  * g_utf8_strrchr:
- * @p: a nul-terminated utf-8 string
- * @len: the maximum length of p
- * @c: a iso-10646 character/
- *
- * Find the rightmost occurence of the given iso-10646 character
- * in a UTF-8 string, while limiting the search to p_len bytes.
- * If len is -1, allow unbounded search.
- *
- * Return value: NULL if the string does not contain the character,
otherwise, a
- *               a pointer to the start of the rightmost of the character
in the string.
+ * @p: a nul-terminated UTF-8 encoded string
+ * @len: the maximum length of @p
+ * @c: a ISO10646 character
+ *
+ * Find the rightmost occurrence of the given ISO10646 character
+ * in a UTF-8 encoded string, while limiting the search to @len bytes.
+ * If @len is -1, allow unbounded search.
+ *
+ * Return value: %NULL if the string does not contain the character,
+ *   otherwise, a pointer to the start of the rightmost occurrence of the
+ *   character in the string.
  **/
 gchar *
 g_utf8_strrchr (const char *p,
@@ -634,10 +636,10 @@

 /**
  * g_utf8_get_char_validated:
- * @p: a pointer to unicode character encoded as UTF-8
+ * @p: a pointer to Unicode character encoded as UTF-8
  * @max_len: the maximum number of bytes to read, or -1, for no maximum.
  *
- * Convert a sequence of bytes encoded as UTF-8 to a unicode character.
+ * Convert a sequence of bytes encoded as UTF-8 to a Unicode character.
  * This function checks for incomplete characters, for invalid characters
  * such as characters that are out of the range of Unicode, and for
  * overlong encodings of valid characters.
@@ -645,7 +647,7 @@
  * Return value: the resulting character. If @p points to a partial
  *    sequence at the end of a string that could begin a valid character,
  *    returns (gunichar)-2; otherwise, if @p does not point to a valid
- *    UTF-8 encoded unicode character, returns (gunichar)-1.
+ *    UTF-8 encoded Unicode character, returns (gunichar)-1.
  **/
 gunichar
 g_utf8_get_char_validated (const  gchar *p,
@@ -664,8 +666,8 @@
 /**
  * g_utf8_to_ucs4_fast:
  * @str: a UTF-8 encoded string
- * @len: the maximum length of @str to use. If < 0, then
- *       the string is %NULL terminated.
+ * @len: the maximum length of @str to use. If @len < 0, then
+ *       the string is nul-terminated.
  * @items_written: location to store the number of characters in the
  *                 result, or %NULL.
  *
@@ -675,7 +677,7 @@
  * but does no error checking on the input.
  *
  * Return value: a pointer to a newly allocated UCS-4 string.
- *               This value must be freed with g_free()
+ *               This value must be freed with g_free().
  **/
 gunichar *
 g_utf8_to_ucs4_fast (const gchar *str,
@@ -769,8 +771,8 @@
 /**
  * g_utf8_to_ucs4:
  * @str: a UTF-8 encoded string
- * @len: the maximum length of @str to use. If < 0, then
- *       the string is %NULL terminated.
+ * @len: the maximum length of @str to use. If @len < 0, then
+ *       the string is nul-terminated.
  * @items_read: location to store number of bytes read, or %NULL.
  *              If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
  *              returned in case @str contains a trailing partial
@@ -853,8 +855,8 @@
 /**
  * g_ucs4_to_utf8:
  * @str: a UCS-4 encoded string
- * @len: the maximum length of @str to use. If < 0, then
- *       the string is %NULL terminated.
+ * @len: the maximum length of @str to use. If @len < 0, then
+ *       the string is terminated with a 0 character.
  * @items_read: location to store number of characters read read, or %NULL.
  * @items_written: location to store number of bytes written or %NULL.
  *                 The value here stored does not include the trailing 0
@@ -926,7 +928,7 @@
 /**
  * g_utf16_to_utf8:
  * @str: a UTF-16 encoded string
- * @len: the maximum length of @str to use. If < 0, then
+ * @len: the maximum length of @str to use. If @len < 0, then
  *       the string is terminated with a 0 character.
  * @items_read: location to store number of words read, or %NULL.
  *              If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
@@ -1070,7 +1072,7 @@
 /**
  * g_utf16_to_ucs4:
  * @str: a UTF-16 encoded string
- * @len: the maximum length of @str to use. If < 0, then
+ * @len: the maximum length of @str to use. If @len < 0, then
  *       the string is terminated with a 0 character.
  * @items_read: location to store number of words read, or %NULL.
  *              If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
@@ -1212,8 +1214,8 @@
 /**
  * g_utf8_to_utf16:
  * @str: a UTF-8 encoded string
- * @len: the maximum length of @str to use. If < 0, then
- *       the string is %NULL terminated.
+ * @len: the maximum length of @str to use. If @len < 0, then
+ *       the string is nul-terminated.

  * @items_read: location to store number of bytes read, or %NULL.
  *              If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
@@ -1330,8 +1332,8 @@
 /**
  * g_ucs4_to_utf16:
  * @str: a UCS-4 encoded string
- * @len: the maximum length of @str to use. If < 0, then
- *       the string is terminated with a zero character.
+ * @len: the maximum length of @str to use. If @len < 0, then
+ *       the string is terminated with a 0 character.
  * @items_read: location to store number of bytes read, or %NULL.
  *              If an error occurs then the index of the invalid input
  *              is stored here.
@@ -1433,12 +1435,12 @@
  * if some bytes were invalid, or the end of the text being validated
  * otherwise).
  *
- * Returns TRUE if all of @str was valid. Many GLib and GTK+
- * routines <emphasis>require</emphasis> valid UTF8 as input;
+ * Returns %TRUE if all of @str was valid. Many GLib and GTK+
+ * routines <emphasis>require</emphasis> valid UTF-8 as input;
  * so data read from a file or the network should be checked
  * with g_utf8_validate() before doing anything else with it.
  *
- * Return value: TRUE if the text was valid UTF-8.
+ * Return value: %TRUE if the text was valid UTF-8
  **/
 gboolean
 g_utf8_validate (const gchar  *str,
Index: glib/gunibreak.c
===================================================================
RCS file: /cvs/gnome/glib/glib/gunibreak.c,v
retrieving revision 1.2
diff -u -b -B -u -r1.2 gunibreak.c
--- glib/gunibreak.c 2001/04/16 20:05:23 1.2
+++ glib/gunibreak.c 2001/09/23 23:10:53
@@ -43,10 +43,10 @@
  * (to derive a character from UTF-8 encoded text, use
  * g_utf8_get_char()). The break type is used to find word and line
  * breaks ("text boundaries"), Pango implements the Unicode boundary
- * resolution alogorithms and normally you would use a function such
+ * resolution algorithms and normally you would use a function such
  * as pango_break() instead of caring about break types yourself.
  *
- * Return value: break type
+ * Return value: the break type of @c
  **/
 GUnicodeBreakType
 g_unichar_break_type (gunichar c)
Index: glib/gunicollate.c
===================================================================
RCS file: /cvs/gnome/glib/glib/gunicollate.c,v
retrieving revision 1.3
diff -u -b -B -u -r1.3 gunicollate.c
--- glib/gunicollate.c 2001/07/11 15:28:35 1.3
+++ glib/gunicollate.c 2001/09/23 23:10:54
@@ -42,8 +42,8 @@
  * compare the keys with strcmp() when sorting instead of
  * sorting the original strings.
  *
- * Return value: -1 if str1 compares before str2, 0 if they
- *   compare equal, 1 if str1 compares after str2.
+ * Return value: -1 if @str1 compares before @str2, 0 if they
+ *   compare equal, 1 if @str1 compares after @str2.
  **/
 gint
 g_utf8_collate (const gchar *str1,
@@ -158,7 +158,7 @@
  * keys with g_utf8_collate().
  *
  * Return value: a newly allocated string. This string should
- *   be freed with g_free when you are done with it.
+ *   be freed with g_free() when you are done with it.
  **/
 gchar *
 g_utf8_collate_key (const gchar *str,
Index: glib/gunidecomp.c
===================================================================
RCS file: /cvs/gnome/glib/glib/gunidecomp.c,v
retrieving revision 1.8
diff -u -b -B -u -r1.8 gunidecomp.c
--- glib/gunidecomp.c 2001/09/02 15:44:21 1.8
+++ glib/gunidecomp.c 2001/09/23 23:10:55
@@ -349,11 +349,11 @@
  * @len: length of @str, in bytes, or -1 if @str is nul-terminated.
  * @mode: the type of normalization to perform.
  *
- * Convert a string into canonical form, standardizing
+ * Converts a string into canonical form, standardizing
  * such issues as whether a character with an accent
  * is represented as a base character and combining
- * accent or as a single precomposed characters. You
- * should generally call g_utf8_normalize before
+ * accent or as a single precomposed character. You
+ * should generally call g_utf8_normalize() before
  * comparing two Unicode strings.
  *
  * The normalization mode %G_NORMALIZE_DEFAULT only
@@ -376,7 +376,8 @@
  * a legacy encoding or pass it to a system with
  * less capable Unicode handling.
  *
- * Return value: the string in normalized form
+ * Return value: a newly allocated string, that is the
+ *   normalized form of @str.
  **/
 gchar *
 g_utf8_normalize (const gchar    *str,
Index: glib/guniprop.c
===================================================================
RCS file: /cvs/gnome/glib/glib/guniprop.c,v
retrieving revision 1.13
diff -u -b -B -u -r1.13 guniprop.c
--- glib/guniprop.c 2001/08/25 22:25:44 1.13
+++ glib/guniprop.c 2001/09/23 23:10:56
@@ -247,11 +247,11 @@

 /**
  * g_unichar_isupper:
- * @c: a unicode character
+ * @c: a Unicode character
  *
  * Determines if a character is uppercase.
  *
- * Return value: %TRUE if @c is an uppercase character.
+ * Return value: %TRUE if @c is an uppercase character
  **/
 gboolean
 g_unichar_isupper (gunichar c)
@@ -261,16 +261,16 @@

 /**
  * g_unichar_istitle:
- * @c: a unicode character
+ * @c: a Unicode character
  *
  * Determines if a character is titlecase. Some characters in
  * Unicode which are composites, such as the DZ digraph
  * have three case variants instead of just two. The titlecase
  * form is used at the beginning of a word where only the
  * first letter is capitalized. The titlecase form of the DZ
- * digraph is U+01F2 LATIN CAPITAL LETTTER D WITH SMALL LETTER Z
+ * digraph is U+01F2 LATIN CAPITAL LETTTER D WITH SMALL LETTER Z.
  *
- * Return value: %TRUE if the character is titlecase.
+ * Return value: %TRUE if the character is titlecase
  **/
 gboolean
 g_unichar_istitle (gunichar c)
@@ -284,11 +284,11 @@

 /**
  * g_unichar_isxdigit:
- * @c: a unicode character.
+ * @c: a Unicode character.
  *
- * Determines if a characters is a hexidecimal digit
+ * Determines if a character is a hexidecimal digit.
  *
- * Return value: %TRUE if the character is a hexadecimal digit.
+ * Return value: %TRUE if the character is a hexadecimal digit
  **/
 gboolean
 g_unichar_isxdigit (gunichar c)
@@ -301,12 +301,12 @@

 /**
  * g_unichar_isdefined:
- * @c: a unicode character
+ * @c: a Unicode character
  *
  * Determines if a given character is assigned in the Unicode
  * standard.
  *
- * Return value: %TRUE if the character has an assigned value.
+ * Return value: %TRUE if the character has an assigned value
  **/
 gboolean
 g_unichar_isdefined (gunichar c)
@@ -317,12 +317,12 @@

 /**
  * g_unichar_iswide:
- * @c: a unicode character
+ * @c: a Unicode character
  *
  * Determines if a character is typically rendered in a double-width
  * cell.
  *
- * Return value: %TRUE if the character is wide.
+ * Return value: %TRUE if the character is wide
  **/
 /* This function stolen from Markus Kuhn <Markus Kuhn cl cam ac uk>.  */
 gboolean
@@ -343,9 +343,9 @@

 /**
  * g_unichar_toupper:
- * @c: a unicode character
+ * @c: a Unicode character
  *
- * Convert a character to uppercase.
+ * Converts a character to uppercase.
  *
  * Return value: the result of converting @c to uppercase.
  *               If @c is not an lowercase or titlecase character,
@@ -380,9 +380,9 @@

 /**
  * g_unichar_tolower:
- * @c: a unicode character.
+ * @c: a Unicode character.
  *
- * Convert a character to lower case
+ * Converts a character to lower case.
  *
  * Return value: the result of converting @c to lower case.
  *               If @c is not an upperlower or titlecase character,
@@ -417,9 +417,9 @@

 /**
  * g_unichar_totitle:
- * @c: a unicode character
+ * @c: a Unicode character
  *
- * Convert a character to the titlecase
+ * Converts a character to the titlecase.
  *
  * Return value: the result of converting @c to titlecase.
  *               If @c is not an uppercase or lowercase character,
@@ -442,13 +442,13 @@

 /**
  * g_unichar_digit_value:
- * @c: a unicode character
+ * @c: a Unicode character
  *
  * Determines the numeric value of a character as a decimal
  * digit.
  *
  * Return value: If @c is a decimal digit (according to
- * `g_unichar_isdigit'), its numeric value. Otherwise, -1.
+ * g_unichar_isdigit()), its numeric value. Otherwise, -1.
  **/
 int
 g_unichar_digit_value (gunichar c)
@@ -460,13 +460,13 @@

 /**
  * g_unichar_xdigit_value:
- * @c: a unicode character
+ * @c: a Unicode character
  *
  * Determines the numeric value of a character as a hexidecimal
  * digit.
  *
  * Return value: If @c is a hex digit (according to
- * `g_unichar_isxdigit'), its numeric value. Otherwise, -1.
+ * g_unichar_isxdigit()), its numeric value. Otherwise, -1.
  **/
 int
 g_unichar_xdigit_value (gunichar c)
@@ -482,7 +482,7 @@

 /**
  * g_unichar_type:
- * @c: a unicode character
+ * @c: a Unicode character
  *
  * Classifies a unicode character by type.
  *
Follow-Ups:
- Re: inline docs
  - From: Havoc Pennington
- Re: inline docs
  - From: Owen Taylor
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]