Re: [patch] minor fixes to gconvert inline API docs

["Matthias Clasen" <matthiasc poet de>]

I my recent work on the docs, I have used nul-terminated in favor of
the other variants, as that seemed to be the most widely used variant.

Matthias

----- Original Message -----
From: "Sven Neumann" <sven gimp org>
To: <gtk-devel-list gnome org>
Sent: Monday, October 01, 2001 3:22 PM
Subject: [patch] minor fixes to gconvert inline API docs


> Hi,
>
> the following patch tries to eliminate a couple of minor issues with
> the inline API docs in glib/gconvert.c. Is it OK to commit this?
>
> I'm not entirely sure how we would like to spell 'NULL-terminated'. At
> the moment, there are a number of different spellings in the docs:
>
>  NULL-terminated
>  NULL terminated
>  %NULL-terminated
>  %NULL terminated
>  nul-terminated
>  nul terminated
>
> which is the preferred one ?
>
>
> Salut, Sven
>
> Index: glib/gconvert.c
> ===================================================================
> RCS file: /cvs/gnome/glib/glib/gconvert.c,v
> retrieving revision 1.21
> diff -u -r1.21 gconvert.c
> --- glib/gconvert.c 2001/09/27 02:49:05 1.21
> +++ glib/gconvert.c 2001/10/01 13:18:05
> @@ -219,22 +219,22 @@
>   * @from_codeset:  character set of @str.
>   * @bytes_read:    location to store the number of bytes in the
>   *                 input string that were successfully converted, or
%NULL.
> - *                 Even if the conversion was succesful, this may be
> - *                 less than len if there were partial characters
> + *                 Even if the conversion was successful, this may be
> + *                 less than @len if there were partial characters
>   *                 at the end of the input. If the error
>   *                 G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value

I think this should be #G_CONVER_ERROR_ILLEGAL_SEQUENCE

> - *                 stored will the byte fofset after the last valid
> + *                 stored will the byte offset after the last valid
>   *                 input sequence.
> - * @bytes_written: the stored in the output buffer (not including the
> - *                 terminating nul.
> + * @bytes_written: the number of bytes stored in the output buffer (not
> + *                 including the terminating NULL).
>   * @error:         location to store the error occuring, or %NULL to
ignore
>   *                 errors. Any of the errors in #GConvertError may occur.
>   *
>   * Convert a string from one character set to another.
>   *
>   * Return value: If the conversion was successful, a newly allocated
> - *               NUL-terminated string, which must be freed with
> - *               g_free. Otherwise %NULL and @error will be set.
> + *               NULL-terminated string, which must be freed with
> + *               g_free(). Otherwise %NULL and @error will be set.
>   **/
>  gchar*
>  g_convert (const gchar *str,
> @@ -282,21 +282,21 @@
>   * @bytes_read:    location to store the number of bytes in the
>   *                 input string that were successfully converted, or
%NULL.
>   *                 Even if the conversion was succesful, this may be
> - *                 less than len if there were partial characters
> + *                 less than @len if there were partial characters
>   *                 at the end of the input. If the error
>   *                 G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value

... and here as well

> - *                 stored will the byte fofset after the last valid
> + *                 stored will the byte offset after the last valid
>   *                 input sequence.
> - * @bytes_written: the stored in the output buffer (not including the
> - *                 terminating nul.
> + * @bytes_written: the number of bytes stored in the output buffer (not
> + *                 including the terminating NULL).
>   * @error:         location to store the error occuring, or %NULL to
ignore
>   *                 errors. Any of the errors in #GConvertError may occur.
>   *
>   * Convert a string from one character set to another.
>   *
>   * Return value: If the conversion was successful, a newly allocated
> - *               NUL-terminated string, which must be freed with
> - *               g_free. Otherwise %NULL and @error will be set.
> + *               NULL-terminated string, which must be freed with
> + *               g_free(). Otherwise %NULL and @error will be set.
>   **/
>  gchar*
>  g_convert_with_iconv (const gchar *str,
> @@ -408,10 +408,10 @@
>   * @bytes_read:   location to store the number of bytes in the
>   *                input string that were successfully converted, or
%NULL.
>   *                Even if the conversion was succesful, this may be
> - *                less than len if there were partial characters
> + *                less than @len if there were partial characters
>   *                at the end of the input.
> - * @bytes_written: the stored in the output buffer (not including the
> - *                 terminating nul.
> + * @bytes_written: the number of bytes stored in the output buffer (not
> + *                including the terminating NULL).
>   * @error:        location to store the error occuring, or %NULL to
ignore
>   *                errors. Any of the errors in #GConvertError may occur.
>   *
> @@ -424,8 +424,8 @@
>   * will simply return that approximate conversion.
>   *
>   * Return value: If the conversion was successful, a newly allocated
> - *               NUL-terminated string, which must be freed with
> - *               g_free. Otherwise %NULL and @error will be set.
> + *               NULL-terminated string, which must be freed with
> + *               g_free(). Otherwise %NULL and @error will be set.
>   **/
>  gchar*
>  g_convert_with_fallback (const gchar *str,
> @@ -666,14 +666,14 @@
>   * @bytes_read:    location to store the number of bytes in the
>   *                 input string that were successfully converted, or
%NULL.
>   *                 Even if the conversion was succesful, this may be
> - *                 less than len if there were partial characters
> + *                 less than @len if there were partial characters
>   *                 at the end of the input. If the error
>   *                 G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value

... and here as well

> - *                 stored will the byte fofset after the last valid
> + *                 stored will the byte offset after the last valid
>   *                 input sequence.
> - * @bytes_written: the stored in the output buffer (not including the
> - *                 terminating nul.
> - * @error: location to store the error occuring, or %NULL to ignore
> + * @bytes_written: the number of bytes stored in the output buffer (not
> + *                 including the terminating NULL).
> + * @error:         location to store the error occuring, or %NULL to
ignore
>   *                 errors. Any of the errors in #GConvertError may occur.
>   *
>   * Converts a string which is in the encoding used for strings by
> @@ -806,14 +806,14 @@
>   * @bytes_read:    location to store the number of bytes in the
>   *                 input string that were successfully converted, or
%NULL.
>   *                 Even if the conversion was succesful, this may be
> - *                 less than len if there were partial characters
> + *                 less than @len if there were partial characters
>   *                 at the end of the input. If the error
>   *                 G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value

...and here...

> - *                 stored will the byte fofset after the last valid
> + *                 stored will the byte offset after the last valid
>   *                 input sequence.
> - * @bytes_written: the stored in the output buffer (not including the
> - *                 terminating nul.
> - * @error: location to store the error occuring, or %NULL to ignore
> + * @bytes_written: the number of bytes stored in the output buffer (not
> + *                 including the terminating NULL).
> + * @error:         location to store the error occuring, or %NULL to
ignore
>   *                 errors. Any of the errors in #GConvertError may occur.
>   *
>   * Converts a string from UTF-8 to the encoding used for strings by
> @@ -952,14 +952,14 @@
>   * @bytes_read:    location to store the number of bytes in the
>   *                 input string that were successfully converted, or
%NULL.
>   *                 Even if the conversion was succesful, this may be
> - *                 less than len if there were partial characters
> + *                 less than @len if there were partial characters
>   *                 at the end of the input. If the error
>   *                 G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
> - *                 stored will the byte fofset after the last valid
> + *                 stored will the byte offset after the last valid
>   *                 input sequence.
> - * @bytes_written: the stored in the output buffer (not including the
> - *                 terminating nul.
> - * @error: location to store the error occuring, or %NULL to ignore
> + * @bytes_written: the number of bytes stored in the output buffer (not
> + *                 including the terminating NULL).
> + * @error:         location to store the error occuring, or %NULL to
ignore
>   *                 errors. Any of the errors in #GConvertError may occur.
>   *
>   * Converts a string which is in the encoding used for filenames
> @@ -991,20 +991,20 @@
>
>  /**
>   * g_filename_from_utf8:
> - * @utf8string:    a UTF-8 encoded string
> + * @utf8string:    a UTF-8 encoded string.
>   * @len:           the length of the string, or -1 if the string is
>   *                 NULL-terminated.
>   * @bytes_read:    location to store the number of bytes in the
>   *                 input string that were successfully converted, or
%NULL.
>   *                 Even if the conversion was succesful, this may be
> - *                 less than len if there were partial characters
> + *                 less than @len if there were partial characters
>   *                 at the end of the input. If the error
>   *                 G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
> - *                 stored will the byte fofset after the last valid
> + *                 stored will the byte offset after the last valid
>   *                 input sequence.
> - * @bytes_written: the stored in the output buffer (not including the
> - *                 terminating nul.
> - * @error: location to store the error occuring, or %NULL to ignore
> + * @bytes_written: the number of bytes stored in the output buffer (not
> + *                 including the terminating NULL).
> + * @error:         location to store the error occuring, or %NULL to
ignore
>   *                 errors. Any of the errors in #GConvertError may occur.
>   *
>   * Converts a string from UTF-8 to the encoding used for filenames.
> @@ -1227,7 +1227,7 @@
>
>  /**
>   * g_filename_from_uri:
> - * @uri: a uri describing a filename (escaped, encoded in UTF-8)
> + * @uri: a uri describing a filename (escaped, encoded in UTF-8).
>   * @hostname: Location to store hostname for the URI, or %NULL.
>   *            If there is no hostname in the URI, %NULL will be
>   *            stored in this location.
>
> _______________________________________________
> gtk-devel-list mailing list
> gtk-devel-list gnome org
> http://mail.gnome.org/mailman/listinfo/gtk-devel-list