From 50c2504186f16ff049ee95cad30fe967b4bdec75 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Thu, 15 Nov 2001 23:03:29 +0000 Subject: [PATCH] Documentation fixes. * glib/giochannel.c: Documentation fixes. * glib/tmpl/iochannels.sgml: Document GIOFlags, fix typos. * glib/tmpl/conversions.sgml, glib/tmpl/unicode.sgml, glib/tmpl/spawn.sgml, glib/tmpl/fileutils.sgml, glib/tmpl/shell.sgml, glib/tmpl/windows.sgml: Add some missing short and long descriptions. --- ChangeLog | 4 + ChangeLog.pre-2-0 | 4 + ChangeLog.pre-2-10 | 4 + ChangeLog.pre-2-12 | 4 + ChangeLog.pre-2-2 | 4 + ChangeLog.pre-2-4 | 4 + ChangeLog.pre-2-6 | 4 + ChangeLog.pre-2-8 | 4 + docs/reference/ChangeLog | 9 +++ docs/reference/glib/tmpl/conversions.sgml | 2 +- docs/reference/glib/tmpl/fileutils.sgml | 2 +- docs/reference/glib/tmpl/iochannels.sgml | 118 ++++++++---------------------- docs/reference/glib/tmpl/shell.sgml | 2 +- docs/reference/glib/tmpl/spawn.sgml | 4 +- docs/reference/glib/tmpl/unicode.sgml | 19 ++++- docs/reference/glib/tmpl/windows.sgml | 2 +- glib/giochannel.c | 71 +++++++++--------- 17 files changed, 129 insertions(+), 132 deletions(-) diff --git a/ChangeLog b/ChangeLog index a689b7c..d145641 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,7 @@ +2001-11-15 Matthias Clasen + + * glib/giochannel.c: Documentation fixes. + 2001-11-15 Takayuki KUSANO * configure.in: Added "ja" to ALL_LINGUAS. diff --git a/ChangeLog.pre-2-0 b/ChangeLog.pre-2-0 index a689b7c..d145641 100644 --- a/ChangeLog.pre-2-0 +++ b/ChangeLog.pre-2-0 @@ -1,3 +1,7 @@ +2001-11-15 Matthias Clasen + + * glib/giochannel.c: Documentation fixes. + 2001-11-15 Takayuki KUSANO * configure.in: Added "ja" to ALL_LINGUAS. diff --git a/ChangeLog.pre-2-10 b/ChangeLog.pre-2-10 index a689b7c..d145641 100644 --- a/ChangeLog.pre-2-10 +++ b/ChangeLog.pre-2-10 @@ -1,3 +1,7 @@ +2001-11-15 Matthias Clasen + + * glib/giochannel.c: Documentation fixes. + 2001-11-15 Takayuki KUSANO * configure.in: Added "ja" to ALL_LINGUAS. diff --git a/ChangeLog.pre-2-12 b/ChangeLog.pre-2-12 index a689b7c..d145641 100644 --- a/ChangeLog.pre-2-12 +++ b/ChangeLog.pre-2-12 @@ -1,3 +1,7 @@ +2001-11-15 Matthias Clasen + + * glib/giochannel.c: Documentation fixes. + 2001-11-15 Takayuki KUSANO * configure.in: Added "ja" to ALL_LINGUAS. diff --git a/ChangeLog.pre-2-2 b/ChangeLog.pre-2-2 index a689b7c..d145641 100644 --- a/ChangeLog.pre-2-2 +++ b/ChangeLog.pre-2-2 @@ -1,3 +1,7 @@ +2001-11-15 Matthias Clasen + + * glib/giochannel.c: Documentation fixes. + 2001-11-15 Takayuki KUSANO * configure.in: Added "ja" to ALL_LINGUAS. diff --git a/ChangeLog.pre-2-4 b/ChangeLog.pre-2-4 index a689b7c..d145641 100644 --- a/ChangeLog.pre-2-4 +++ b/ChangeLog.pre-2-4 @@ -1,3 +1,7 @@ +2001-11-15 Matthias Clasen + + * glib/giochannel.c: Documentation fixes. + 2001-11-15 Takayuki KUSANO * configure.in: Added "ja" to ALL_LINGUAS. diff --git a/ChangeLog.pre-2-6 b/ChangeLog.pre-2-6 index a689b7c..d145641 100644 --- a/ChangeLog.pre-2-6 +++ b/ChangeLog.pre-2-6 @@ -1,3 +1,7 @@ +2001-11-15 Matthias Clasen + + * glib/giochannel.c: Documentation fixes. + 2001-11-15 Takayuki KUSANO * configure.in: Added "ja" to ALL_LINGUAS. diff --git a/ChangeLog.pre-2-8 b/ChangeLog.pre-2-8 index a689b7c..d145641 100644 --- a/ChangeLog.pre-2-8 +++ b/ChangeLog.pre-2-8 @@ -1,3 +1,7 @@ +2001-11-15 Matthias Clasen + + * glib/giochannel.c: Documentation fixes. + 2001-11-15 Takayuki KUSANO * configure.in: Added "ja" to ALL_LINGUAS. diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index a0cdd64..331a1d3 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,12 @@ +2001-11-15 Matthias Clasen + + * glib/tmpl/iochannels.sgml: Document GIOFlags, fix typos. + + * glib/tmpl/conversions.sgml, glib/tmpl/unicode.sgml, + glib/tmpl/spawn.sgml, glib/tmpl/fileutils.sgml, + glib/tmpl/shell.sgml, glib/tmpl/windows.sgml: Add + some missing short and long descriptions. + 2001-11-14 Matthias Clasen * glib/Makefile.am (MKDB_OPTIONS): Add --sgml-mode. diff --git a/docs/reference/glib/tmpl/conversions.sgml b/docs/reference/glib/tmpl/conversions.sgml index c43a987..cc0affc 100644 --- a/docs/reference/glib/tmpl/conversions.sgml +++ b/docs/reference/glib/tmpl/conversions.sgml @@ -2,7 +2,7 @@ Character Set Conversion - +convert strings between different character sets using iconv() diff --git a/docs/reference/glib/tmpl/fileutils.sgml b/docs/reference/glib/tmpl/fileutils.sgml index 5949194..b70b875 100644 --- a/docs/reference/glib/tmpl/fileutils.sgml +++ b/docs/reference/glib/tmpl/fileutils.sgml @@ -2,7 +2,7 @@ File Utilities - +various file-related functions. diff --git a/docs/reference/glib/tmpl/iochannels.sgml b/docs/reference/glib/tmpl/iochannels.sgml index 91a5b68..88b6760 100644 --- a/docs/reference/glib/tmpl/iochannels.sgml +++ b/docs/reference/glib/tmpl/iochannels.sgml @@ -9,13 +9,13 @@ portable support for using files, pipes and sockets. The #GIOChannel data type aims to provide a portable method for using file descriptors, pipes, and sockets, and integrating them into the main event loop. -Currently full support is available on Unix platforms, though support for +Currently full support is available on Unix platforms, support for Windows is only partially complete. To create a new #GIOChannel on Unix systems use g_io_channel_unix_new(). This works for plain file descriptors, pipes and sockets. -Alternately, a channel can be created for a file in a system independent +Alternatively, a channel can be created for a file in a system independent manner using g_io_channel_new_file(). @@ -51,7 +51,7 @@ The new functions g_io_channel_read_chars(), g_io_channel_read_line(), g_io_channel_read_line_string(), g_io_channel_read_to_end(), g_io_channel_write_chars(), g_io_channel_seek_position(), and g_io_channel_flush() should not be mixed with the -depricated functions g_io_channel_read(), g_io_channel_write(), +deprecated functions g_io_channel_read(), g_io_channel_write(), and g_io_channel_seek() on the same channel. @@ -213,8 +213,6 @@ programmer (unless you are creating a new type of #GIOChannel). @channel: @error: @Returns: - -@err: @@ -227,41 +225,17 @@ programmer (unless you are creating a new type of #GIOChannel). @type: @error: @Returns: - -@err: An enumeration specifying the base position for a g_io_channel_seek_position() operation. - - - - - - -G_SEEK_CUR -the current position in the file. - - - -G_SEEK_SET -the start of the file. - - - -G_SEEK_END -the end of the file. - - - - -@G_SEEK_CUR: -@G_SEEK_SET: -@G_SEEK_END: +@G_SEEK_CUR: the current position in the file. +@G_SEEK_SET: the start of the file. +@G_SEEK_END: the end of the file. @@ -381,52 +355,15 @@ with the given priority. A bitwise combination representing a condition to watch for on an event source. - - - - - - -G_IO_IN -There is data to read. - - - -G_IO_OUT -Data can be written (without blocking). - - - -G_IO_PRI -There is urgent data to read. - - - -G_IO_ERR -Error condition. - - - -G_IO_HUP -Hung up (the connection has been broken, usually for pipes and -sockets). - - - -G_IO_NVAL -Invalid request. The file descriptor is not open. - - - - -@G_IO_IN: -@G_IO_OUT: -@G_IO_PRI: -@G_IO_ERR: -@G_IO_HUP: -@G_IO_NVAL: +@G_IO_IN: There is data to read. +@G_IO_OUT: Data can be written (without blocking). +@G_IO_PRI: There is urgent data to read. +@G_IO_ERR: Error condition. +@G_IO_HUP: Hung up (the connection has been broken, usually for pipes + and sockets). +@G_IO_NVAL: Invalid request. The file descriptor is not open. @@ -491,9 +428,6 @@ generic way. @channel: @Returns: - -@flags: -@error: @@ -509,14 +443,22 @@ generic way. - - - -@G_IO_FLAG_APPEND: -@G_IO_FLAG_NONBLOCK: -@G_IO_FLAG_IS_READABLE: -@G_IO_FLAG_IS_WRITEABLE: -@G_IO_FLAG_IS_SEEKABLE: +Specifies properties of a #GIOChannel. Some of the flags can only +be read with g_io_channel_get_flags(), but not changed with +g_io_channel_set_flags(). + + +@G_IO_FLAG_APPEND: turns on append mode, corresponds to %O_APPEND (see the + documentation of the Unix open() syscall). +@G_IO_FLAG_NONBLOCK: turns on nonblocking mode, corresponds to + %O_NONBLOCK/%O_NDELAY (see the documentation of the Unix + open() syscall). +@G_IO_FLAG_IS_READABLE: indicates that the io channel is readable. This flag + can not be changed. +@G_IO_FLAG_IS_WRITEABLE: indicates that the io channel is writable. This flag + can not be changed. +@G_IO_FLAG_IS_SEEKABLE: indicates that the io channel is seekable, i.e. that + g_io_channel_seek_position() can be used on it. This flag can not be changed. @G_IO_FLAG_MASK: @G_IO_FLAG_GET_MASK: @G_IO_FLAG_SET_MASK: @@ -610,7 +552,7 @@ generic way. -#GIOError is only used by the depricated functions g_io_channel_read(), +#GIOError is only used by the deprecated functions g_io_channel_read(), g_io_channel_write(), and g_io_channel_seek(). diff --git a/docs/reference/glib/tmpl/shell.sgml b/docs/reference/glib/tmpl/shell.sgml index 99d859f..34efec3 100644 --- a/docs/reference/glib/tmpl/shell.sgml +++ b/docs/reference/glib/tmpl/shell.sgml @@ -2,7 +2,7 @@ Shell-related Utilities - +shell-like commandline handling diff --git a/docs/reference/glib/tmpl/spawn.sgml b/docs/reference/glib/tmpl/spawn.sgml index 9426a77..c54b741 100644 --- a/docs/reference/glib/tmpl/spawn.sgml +++ b/docs/reference/glib/tmpl/spawn.sgml @@ -1,8 +1,8 @@ -Spawning Processes (fork/exec) +Spawning Processes - +Process launching with fork()/exec() diff --git a/docs/reference/glib/tmpl/unicode.sgml b/docs/reference/glib/tmpl/unicode.sgml index 1bab836..b9811a6 100644 --- a/docs/reference/glib/tmpl/unicode.sgml +++ b/docs/reference/glib/tmpl/unicode.sgml @@ -2,16 +2,31 @@ Unicode Manipulation - +functions operating on Unicode characters and UTF-8 strings. - +This section describes a number of functions for dealing with +Unicode characters and strings. There are analogues of the +traditional ctype.h character classification +and case conversion functions, UTF-8 analogues of some string utility +functions, functions to perform normalization, case conversion and +collation on UTF-8 strings and finally functions to convert between +the UTF-8, UTF-16 and UCS-4 encodings of Unicode. + + + +g_locale_to_utf8(), g_locale_from_utf8() + +Convenience functions for converting between UTF-8 and the locale encoding. + + + diff --git a/docs/reference/glib/tmpl/windows.sgml b/docs/reference/glib/tmpl/windows.sgml index dec9fda..ca68b01 100644 --- a/docs/reference/glib/tmpl/windows.sgml +++ b/docs/reference/glib/tmpl/windows.sgml @@ -2,7 +2,7 @@ Windows Compatibility Functions - +Unix emulation on Windows diff --git a/glib/giochannel.c b/glib/giochannel.c index fd952ed..69036d7 100644 --- a/glib/giochannel.c +++ b/glib/giochannel.c @@ -160,7 +160,7 @@ g_io_error_get_from_g_error (GIOStatus status, * @count: the number of bytes to read from the #GIOChannel. * @bytes_read: returns the number of bytes actually read. * - * Reads data from a #GIOChannel. This function is depricated. New code should + * Reads data from a #GIOChannel. This function is deprecated. New code should * use g_io_channel_read_chars() instead. * * Return value: %G_IO_ERROR_NONE if the operation was successful. @@ -195,7 +195,7 @@ g_io_channel_read (GIOChannel *channel, * @count: the number of bytes to write. * @bytes_written: the number of bytes actually written. * - * Writes data to a #GIOChannel. This function is depricated. New code should + * Writes data to a #GIOChannel. This function is deprecated. New code should * use g_io_channel_write_chars() instead. * * Return value: %G_IO_ERROR_NONE if the operation was successful. @@ -232,8 +232,8 @@ g_io_channel_write (GIOChannel *channel, * file). * * Sets the current position in the #GIOChannel, similar to the standard library - * function fseek(). This function is depricated. New code should - * use g_io_channel_seek_position() instead. + * function fseek(). This function is deprecated. New + * code should use g_io_channel_seek_position() instead. * * Return value: %G_IO_ERROR_NONE if the operation was successful. **/ @@ -278,7 +278,7 @@ g_io_channel_seek (GIOChannel *channel, * g_io_channel_new_file: * @filename: A string containing the name of a file. * @mode: One of "r", "w", "a", "r+", "w+", "a+". These have - * the same meaning as in fopen(). + * the same meaning as in fopen(). * @error: A location to return an error of type %G_IO_FILE_ERROR. * * Open a file @filename as a #GIOChannel using mode @mode. This @@ -592,7 +592,7 @@ g_io_channel_error_from_errno (gint en) * @channel: a #GIOChannel * @size: the size of the buffer. 0 == pick a good size * - * Set the buffer size. + * Sets the buffer size. **/ void g_io_channel_set_buffer_size (GIOChannel *channel, @@ -613,7 +613,7 @@ g_io_channel_set_buffer_size (GIOChannel *channel, * g_io_channel_get_buffer_size: * @channel: a #GIOChannel * - * Get the buffer size. + * Gets the buffer size. * * Return value: the size of the buffer. **/ @@ -630,11 +630,11 @@ g_io_channel_get_buffer_size (GIOChannel *channel) * @channel: a #GIOChannel * @line_term: The line termination string. Use %NULL for auto detect. * Auto detection breaks on "\n", "\r\n", "\r", "\0", and - * the unicode paragraph separator. Auto detection should + * the Unicode paragraph separator. Auto detection should * not be used for anything other than file-based channels. * @length: The length of the termination string. If -1 is passed, the - * string is assumed to be null terminated. This option allows - * termination strings with embeded nulls. + * string is assumed to be nul-terminated. This option allows + * termination strings with embeded nuls. * * This sets the string that #GIOChannel uses to determine * where in the file a line break occurs. @@ -685,10 +685,10 @@ g_io_channel_get_line_term (GIOChannel *channel, /** * g_io_channel_set_flags: * @channel: a #GIOChannel. - * @flags: the flags to set on the channel. + * @flags: the flags to set on the IO channel. * @error: A location to return an error of type #GIOChannelError. * - * Sets flags on the channel. + * Sets flags on the IO channel. * * Return value: the status of the operation. **/ @@ -716,7 +716,7 @@ g_io_channel_set_flags (GIOChannel *channel, * The values of the flags %G_IO_FLAG_IS_READABLE and %G_IO_FLAG_IS_WRITEABLE * are cached for internal use by the channel when it is created. * If they should change at some later point (e.g. partial shutdown - * of a socket with the unix shutdown () function), the user + * of a socket with the Unix shutdown() function), the user * should immediately call g_io_channel_get_flags () to update * the internal values of these flags. * @@ -890,11 +890,11 @@ g_io_channel_seek_position (GIOChannel* channel, * @channel: a #GIOChannel * @error: location to store an error of type #GIOChannelError * - * Flush the write buffer for the GIOChannel. + * Flushes the write buffer for the GIOChannel. * * Return value: the status of the operation: One of - * G_IO_CHANNEL_NORMAL, G_IO_CHANNEL_AGAIN, or - * G_IO_CHANNEL_ERROR. + * #G_IO_CHANNEL_NORMAL, #G_IO_CHANNEL_AGAIN, or + * #G_IO_CHANNEL_ERROR. **/ GIOStatus g_io_channel_flush (GIOChannel *channel, @@ -937,7 +937,7 @@ g_io_channel_flush (GIOChannel *channel, * * A buffered channel can only be set unbuffered if the channel's * internal buffers have been flushed. Newly created channels or - * channels which have returned G_IO_STATUS_EOF + * channels which have returned %G_IO_STATUS_EOF * not require such a flush. For write-only channels, a call to * g_io_channel_flush () is sufficient. For all other channels, * the buffers may be flushed by a call to g_io_channel_seek_position (). @@ -993,7 +993,7 @@ g_io_channel_get_buffered (GIOChannel *channel) * @encoding: the encoding type * @error: location to store an error of type #GConvertError. * - * Set the encoding for the input/output of the channel. The internal + * Sets the encoding for the input/output of the channel. The internal * encoding is always UTF-8. The default encoding for the * external file is UTF-8. * @@ -1012,15 +1012,15 @@ g_io_channel_get_buffered (GIOChannel *channel) * * 4. The current encoding is %NULL or UTF-8. * - * 5. One of the (new API) read functions has just returned G_IO_STATUS_EOF - * (or, in the case of g_io_channel_read_to_end (), G_IO_STATUS_NORMAL). + * 5. One of the (new API) read functions has just returned %G_IO_STATUS_EOF + * (or, in the case of g_io_channel_read_to_end (), %G_IO_STATUS_NORMAL). * * 6. One of the functions g_io_channel_read_chars () or g_io_channel_read_unichar () - * has returned G_IO_STATUS_AGAIN or G_IO_STATUS_ERROR. This may be - * useful in the case of G_CONVERT_ERROR_ILLEGAL_SEQUENCE. + * has returned %G_IO_STATUS_AGAIN or %G_IO_STATUS_ERROR. This may be + * useful in the case of %G_CONVERT_ERROR_ILLEGAL_SEQUENCE. * Returning one of these statuses from g_io_channel_read_line (), * g_io_channel_read_line_string (), or g_io_channel_read_to_end () - * does _not_ guarantee that the encoding can be changed. + * does not guarantee that the encoding can be changed. * * Channels which do not meet the above conditions cannot call * g_io_channel_seek_position () with an offset of %G_SEEK_CUR, @@ -1028,7 +1028,7 @@ g_io_channel_get_buffered (GIOChannel *channel) * call g_io_channel_write_chars () after calling one * of the API "read" functions. * - * Return Value: %G_IO_STATUS_NORMAL if the encoding was succesfully set. + * Return Value: %G_IO_STATUS_NORMAL if the encoding was successfully set. **/ GIOStatus g_io_channel_set_encoding (GIOChannel *channel, @@ -1158,7 +1158,7 @@ g_io_channel_set_encoding (GIOChannel *channel, * g_io_channel_get_encoding: * @channel: a #GIOChannel * - * Get the encoding for the input/output of the channel. The internal + * Gets the encoding for the input/output of the channel. The internal * encoding is always UTF-8. The encoding %NULL makes the * channel safe for binary data. * @@ -1350,20 +1350,19 @@ reencode: * @channel: a #GIOChannel * @str_return: The line read from the #GIOChannel, not including the * line terminator. This data should be freed with g_free() - * when no longer needed. This - * is a null terminated string. If a @length of zero is - * returned, this will be %NULL instead. + * when no longer needed. This is a nul-terminated string. + * If a @length of zero is returned, this will be %NULL instead. * @length: location to store length of the read data, or %NULL * @terminator_pos: location to store position of line terminator, or %NULL * @error: A location to return an error of type #GConvertError * or #GIOChannelError * - * Read a line, including the terminating character(s), - * from a #GIOChannel into a newly allocated string. + * Reads a line, including the terminating character(s), + * from a #GIOChannel into a newly-allocated string. * @length will contain allocated memory if the return * is %G_IO_STATUS_NORMAL. * - * Return value: a newly allocated string. Free this string + * Return value: a newly-allocated string. Free this string * with g_free() when you are done with it. **/ GIOStatus @@ -1409,7 +1408,7 @@ g_io_channel_read_line (GIOChannel *channel, * @error: a location to store an error of type #GConvertError * or #GIOChannelError * - * Read a line from a #GIOChannel, using a #GString as a buffer. + * Reads a line from a #GIOChannel, using a #GString as a buffer. * * Return value: the status of the operation. **/ @@ -1613,13 +1612,13 @@ done: * @str_return: Location to store a pointer to a string holding * the remaining data in the #GIOChannel. This data should * be freed with g_free() when no longer needed. This - * data is terminated by an extra null, but there may be other - * nulls in the intervening data. + * data is terminated by an extra nul character, but there + * may be other nuls in the intervening data. * @length: Location to store length of the data * @error: A location to return an error of type #GConvertError * or #GIOChannelError * - * Read all the remaining data from the file. + * Reads all the remaining data from the file. * * Return value: %G_IO_STATUS_NORMAL on success. This function never * returns %G_IO_STATUS_EOF. @@ -1873,7 +1872,7 @@ g_io_channel_read_unichar (GIOChannel *channel, * @channel: a #GIOChannel * @buf: a buffer to write data from * @count: the size of the buffer. If -1, the buffer - * is taken to be a nul terminated string. + * is taken to be a nul-terminated string. * @bytes_written: The number of bytes written. This can be nonzero * even if the return value is not %G_IO_STATUS_NORMAL. * If the return value is %G_IO_STATUS_NORMAL and the -- 2.7.4