Commit d761fb4b authored by Matthias Clasen's avatar Matthias Clasen
Browse files

documentation update. add documentation. update docs. Remove references to

        * glib/gstrfuncs.c, glib/giochannel.c: documentation update.
        * glib/gqueue.c: add documentation.
        * glib/tmpl/iochannel.sgml, glib/tmpl/macros_misc.sgml,
          glib/tmpl/queue.sgml: update docs.
        * glib/tmpl/modules.sgml, glib/tmpl/threads.sgml: Remove
          references to glib-config.
parent c414f5c1
2001-10-02 Matthias Clasen <matthiasc@poet.de>
* glib/gstrfuncs.c, glib/giochannel.c: documentation update.
* glib/gqueue.c: add documentation.
2001-10-02 Sven Neumann <sven@gimp.org>
* glib/gstring.h (g_string_sprintfa): let the compatibility definition
......
2001-10-02 Matthias Clasen <matthiasc@poet.de>
* glib/gstrfuncs.c, glib/giochannel.c: documentation update.
* glib/gqueue.c: add documentation.
2001-10-02 Sven Neumann <sven@gimp.org>
* glib/gstring.h (g_string_sprintfa): let the compatibility definition
......
2001-10-02 Matthias Clasen <matthiasc@poet.de>
* glib/gstrfuncs.c, glib/giochannel.c: documentation update.
* glib/gqueue.c: add documentation.
2001-10-02 Sven Neumann <sven@gimp.org>
* glib/gstring.h (g_string_sprintfa): let the compatibility definition
......
2001-10-02 Matthias Clasen <matthiasc@poet.de>
* glib/gstrfuncs.c, glib/giochannel.c: documentation update.
* glib/gqueue.c: add documentation.
2001-10-02 Sven Neumann <sven@gimp.org>
* glib/gstring.h (g_string_sprintfa): let the compatibility definition
......
2001-10-02 Matthias Clasen <matthiasc@poet.de>
* glib/gstrfuncs.c, glib/giochannel.c: documentation update.
* glib/gqueue.c: add documentation.
2001-10-02 Sven Neumann <sven@gimp.org>
* glib/gstring.h (g_string_sprintfa): let the compatibility definition
......
2001-10-02 Matthias Clasen <matthiasc@poet.de>
* glib/gstrfuncs.c, glib/giochannel.c: documentation update.
* glib/gqueue.c: add documentation.
2001-10-02 Sven Neumann <sven@gimp.org>
* glib/gstring.h (g_string_sprintfa): let the compatibility definition
......
2001-10-02 Matthias Clasen <matthiasc@poet.de>
* glib/gstrfuncs.c, glib/giochannel.c: documentation update.
* glib/gqueue.c: add documentation.
2001-10-02 Sven Neumann <sven@gimp.org>
* glib/gstring.h (g_string_sprintfa): let the compatibility definition
......
2001-10-02 Matthias Clasen <matthiasc@poet.de>
* glib/gstrfuncs.c, glib/giochannel.c: documentation update.
* glib/gqueue.c: add documentation.
2001-10-02 Sven Neumann <sven@gimp.org>
* glib/gstring.h (g_string_sprintfa): let the compatibility definition
......
2001-10-02 Matthias Clasen <matthiasc@poet.de>
* glib/tmpl/iochannel.sgml, glib/tmpl/macros_misc.sgml,
glib/tmpl/queue.sgml: update docs.
* glib/tmpl/modules.sgml, glib/tmpl/threads.sgml: Remove
references to glib-config.
2001-10-01 Matthias Clasen <matthiasc@poet.de>
* glib/tmpl/iochannels.sgml, glib/tmpl/shell.sgml,
......
......@@ -295,7 +295,7 @@ Error codes returned by #GIOChannel operations.
@G_IO_CHANNEL_ERROR_ISDIR: File is a directory.
@G_IO_CHANNEL_ERROR_NOSPC: No space left on device.
@G_IO_CHANNEL_ERROR_NXIO: No such device or address.
@G_IO_CHANNEL_ERROR_OVERFLOW:
@G_IO_CHANNEL_ERROR_OVERFLOW: Value too large for defined datatype.
@G_IO_CHANNEL_ERROR_PIPE: Broken pipe.
@G_IO_CHANNEL_ERROR_FAILED: Some other error.
......
......@@ -98,15 +98,6 @@ when compiling with the <literal>-pedantic</literal> option.
<!-- ##### MACRO G_GNUC_CONST ##### -->
<para>
Expands to the GNU C const function attribute if the compiler is GNU C.
This enables optimization of the function.
See the GNU C documentation for details.
</para>
<!-- ##### MACRO G_GNUC_NORETURN ##### -->
<para>
Expands to the GNU C noreturn function attribute if the compiler is GNU C.
......@@ -129,9 +120,20 @@ It avoids possible compiler warnings. See the GNU C documentation for details.
<!-- ##### MACRO G_GNUC_PURE ##### -->
<para>
Expands to the GNU C pure function attribute if the compiler is GNU C.
Declaring a function as pure enables better optimization of the function.
A pure function has no effects except its return value and the return
value depends only on the parameters and/or global variables.
See the GNU C documentation for details.
</para>
FIXME: Explain what pure functions are.
<!-- ##### MACRO G_GNUC_CONST ##### -->
<para>
Expands to the GNU C const function attribute if the compiler is GNU C.
Declaring a function as const enables better optimization of the function.
A const function doesn't examine any values except its parameters,
and has no effects except its return value.
See the GNU C documentation for details.
</para>
......@@ -144,6 +146,12 @@ arguments, with the same syntax as <function>printf()</function>.
It allows the compiler to type-check the arguments passed to the function.
See the GNU C documentation for details.
</para>
<informalexample><programlisting>
gint g_snprintf (gchar *string,
gulong n,
gchar const *format,
...) G_GNUC_PRINTF (3, 4);
</programlisting></informalexample>
@format_idx: the index of the argument corresponding to the format string.
(The arguments are numbered from 1).
......@@ -167,12 +175,19 @@ See the GNU C documentation for details.
<!-- ##### MACRO G_GNUC_FORMAT ##### -->
<para>
Expands to the GNU C format_arg function attribute if the compiler is GNU C.
This is used for declaring functions which take a variable number of
parameters, like <function>printf()</function> and
<function>scanf()</function>. See the GNU C documentation for details.
FIXME: I can't find this in my GNU C documentation. Take out?
The format_arg function attribute specifies that a function takes a format
string for a <function>printf()</function>, <function>scanf()</function>,
<function>strftime()</function> or <function>strfmon()</function> style
function and modifies it, so that the result can be passed to a
<function>printf()</function>, <function>scanf()</function>,
<function>strftime()</function> or <function>strfmon()</function> style
function (with the remaining arguments to the format function the same as
they would have been for the unmodified string).
See the GNU C documentation for details.
</para>
<informalexample><programlisting>
gchar *g_dgettext (gchar *domain_name, gchar *msgid) G_GNUC_FORMAT (2);
</programlisting></informalexample>
@arg_idx: the index of the argument.
......@@ -203,10 +218,10 @@ GNU C documentation for details.
<!-- ##### MACRO G_GNUC_NO_INSTRUMENT ##### -->
<para>
Expands to the GNU C no_instrument_function function attribute if
the compiler is GNU C.
the compiler is GNU C. Functions with this attribute will not be
instrumented for profiling, when the compiler is called with the
<option>-finstrument-functions</option> option.
See the GNU C documentation for details.
FIXME: Explain no_instrument_function.
</para>
......
......@@ -14,8 +14,8 @@ an implementation of <function>dlopen()</function> (e.g. Linux/Sun), as well as
</para>
<para>
A program, which wants to use these functions must be linked to the
libraries output by the command <command>glib-config --libs gmodule</command>.
A program which wants to use these functions must be linked to the
libraries output by the command <command>pkg-config --libs gmodule-2.0</command>.
</para>
<para>
......
<!-- ##### SECTION Title ##### -->
Glob-style pattern matching
<!-- ##### SECTION Short_Description ##### -->
<!-- ##### SECTION Long_Description ##### -->
<para>
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<!-- ##### ENUM GMatchType ##### -->
<para>
</para>
@G_MATCH_ALL:
@G_MATCH_ALL_TAIL:
@G_MATCH_HEAD:
@G_MATCH_TAIL:
@G_MATCH_EXACT:
@G_MATCH_LAST:
<!-- ##### STRUCT GPatternSpec ##### -->
<para>
</para>
@match_type:
@pattern_length:
@pattern:
@pattern_reversed:
<!-- ##### FUNCTION g_pattern_spec_new ##### -->
<para>
</para>
@pattern:
@Returns:
<!-- ##### FUNCTION g_pattern_spec_free ##### -->
<para>
</para>
@pspec:
<!-- ##### FUNCTION g_pattern_match ##### -->
<para>
</para>
@pspec:
@string_length:
@string:
@string_reversed:
@Returns:
<!-- ##### FUNCTION g_pattern_match_string ##### -->
<para>
</para>
@pspec:
@string:
@Returns:
<!-- ##### FUNCTION g_pattern_match_simple ##### -->
<para>
</para>
@pattern:
@string:
@Returns:
......@@ -2,12 +2,32 @@
Double-ended Queues
<!-- ##### SECTION Short_Description ##### -->
Double-ended queue data structure
double-ended queue data structure
<!-- ##### SECTION Long_Description ##### -->
<para>
The #GQueue structure and its associated functions provide a standard
queue data structure. Internally, #GQueue uses the same data structure as
#GList to store elements.
</para>
<para>
The data contained in each element can be either integer values, by using one
of the
<link linkend="glib-Type-Conversion-Macros">Type Conversion Macros</link>,
or simply pointers to any type of data.
</para>
<para>
To create a new #GQueue, use g_queue_new().
</para>
<para>
To add elements, use g_queue_push_head(), g_queue_push_head_link(),
g_queue_push_tail() and g_queue_push_tail_link().
</para>
<para>
To remove elements, use g_queue_pop_head() and g_queue_pop_tail().
</para>
<para>
To free the entire queue, use g_queue_free().
</para>
<!-- ##### SECTION See_Also ##### -->
......@@ -17,12 +37,12 @@ Double-ended queue data structure
<!-- ##### STRUCT GQueue ##### -->
<para>
Contains the public fields of a <link linkend="glib-queues">Queue</link>.
</para>
@head:
@tail:
@length:
@head: a pointer to the first element of the queue.
@tail: a pointer to the last element of the queue.
@length: the number of elements in the queue.
<!-- ##### FUNCTION g_queue_new ##### -->
<para>
......
......@@ -191,10 +191,9 @@ elements of @vtable are non-%NULL, then g_thread_init() will abort.
<note>
<para>
To use g_thread_init() in your program, you have to link with the
libraries, that the command "glib-config --libs gthread" outputs. This
is not the case for all the other thread related functions of
GLib. Those can be used without having to link with the thread
libraries.
libraries that the command <command>pkg-config --libs gthread-2.0</command>
outputs. This is not the case for all the other thread related functions of
GLib. Those can be used without having to link with the thread libraries.
</para>
</note>
......
......@@ -333,7 +333,7 @@ g_io_channel_close (GIOChannel *channel)
* flushed if @flush is %TRUE. The channel will not be freed until the
* last reference is dropped using g_io_channel_unref().
*
* Return value:
* Return value: the status of the operation.
**/
GIOStatus
g_io_channel_shutdown (GIOChannel *channel,
......@@ -512,9 +512,11 @@ g_io_channel_get_buffer_condition (GIOChannel *channel)
/**
* g_io_channel_error_from_errno:
* @en: An errno error number, e.g. EINVAL
* @en: an <literal>errno</literal> error number, e.g. %EINVAL.
*
* Return value: A #GIOChannelError error number, e.g. %G_IO_CHANNEL_ERROR_INVAL
* Converts an <literal>errno</literal> error number to a #GIOChannelError.
*
* Return value: a #GIOChannelError error number, e.g. %G_IO_CHANNEL_ERROR_INVAL.
**/
GIOChannelError
g_io_channel_error_from_errno (gint en)
......@@ -682,11 +684,13 @@ g_io_channel_get_line_term (GIOChannel *channel,
/**
* g_io_channel_set_flags:
* @channel: a #GIOChannel
* @flags: the flags to set on the channel
* @error: A location to return an error of type #GIOChannelError
* @channel: a #GIOChannel.
* @flags: the flags to set on the channel.
* @error: A location to return an error of type #GIOChannelError.
*
* Sets flags on the channel.
*
* Return value:
* Return value: the status of the operation.
**/
GIOStatus
g_io_channel_set_flags (GIOChannel *channel,
......@@ -761,12 +765,15 @@ g_io_channel_set_close_on_unref (GIOChannel *channel,
/**
* g_io_channel_get_close_on_unref:
* @channel: a #GIOChannel
* @channel: a #GIOChannel.
*
* Return value: Whether the channel will be closedi on the final unref of
* the GIOChannel data structure. The default value of
* this is %TRUE for channels created by g_io_channel_new_file (),
* and %FALSE for all other channels.
* Returns whether the channel will be closed on the final unref of the
* #GIOChannel data structure. The default value of this is %TRUE for
* channels created by g_io_channel_new_file(), and %FALSE for all other
* channels.
*
* Return value: %TRUE if the channel will be closed on the final unref of
* the #GIOChannel data structure.
**/
gboolean
g_io_channel_get_close_on_unref (GIOChannel *channel)
......@@ -788,7 +795,7 @@ g_io_channel_get_close_on_unref (GIOChannel *channel)
*
* Replacement for g_io_channel_seek() with the new API.
*
* Return value:
* Return value: the status of the operation.
**/
GIOStatus
g_io_channel_seek_position (GIOChannel* channel,
......@@ -966,9 +973,11 @@ g_io_channel_set_buffered (GIOChannel *channel,
/**
* g_io_channel_get_buffered:
* @channel: a #GIOChannel
* @channel: a #GIOChannel.
*
* Returns the buffering state of the channel.
*
* Return Value: the buffering state of the channel
* Return Value: %TRUE if the @channel is buffered.
**/
gboolean
g_io_channel_get_buffered (GIOChannel *channel)
......@@ -1402,7 +1411,7 @@ g_io_channel_read_line (GIOChannel *channel,
*
* Read a line from a #GIOChannel, using a #GString as a buffer.
*
* Return value:
* Return value: the status of the operation.
**/
GIOStatus
g_io_channel_read_line_string (GIOChannel *channel,
......@@ -1696,7 +1705,7 @@ g_io_channel_read_to_end (GIOChannel *channel,
*
* Replacement for g_io_channel_read() with the new API.
*
* Return value:
* Return value: the status of the operation.
**/
GIOStatus
g_io_channel_read_chars (GIOChannel *channel,
......@@ -1880,7 +1889,7 @@ g_io_channel_read_unichar (GIOChannel *channel,
* may only be made on a channel from which data has been read in the
* cases described in the documentation for g_io_channel_set_encoding ().
*
* Return value:
* Return value: the status of the operation.
**/
GIOStatus
g_io_channel_write_chars (GIOChannel *channel,
......
......@@ -35,6 +35,13 @@ G_LOCK_DEFINE_STATIC (queue_memchunk);
static GMemChunk *queue_memchunk = NULL;
static GTrashStack *free_queue_nodes = NULL;
/**
* g_queue_new:
*
* Creates a new #GQueue.
*
* Returns: a new #GQueue.
**/
GQueue*
g_queue_new (void)
{
......@@ -61,6 +68,12 @@ g_queue_new (void)
return queue;
}
/**
* g_queue_free:
* @queue: a #GQueue.
*
* Frees the memory allocated for the #GQueue.
**/
void
g_queue_free (GQueue *queue)
{
......@@ -78,6 +91,13 @@ g_queue_free (GQueue *queue)
G_UNLOCK (queue_memchunk);
}
/**
* g_queue_push_head:
* @queue: a #GQueue.
* @data: the data for the new element.
*
* Adds a new element at the head of the queue.
**/
void
g_queue_push_head (GQueue *queue,
gpointer data)
......@@ -90,6 +110,14 @@ g_queue_push_head (GQueue *queue,
queue->length++;
}
/**
* g_queue_push_head_link:
* @queue: a #GQueue.
* @link: a single #GList element, <emphasis>not</emphasis> a list with
* more than one element.
*
* Adds a new element at the head of the queue.
**/
void
g_queue_push_head_link (GQueue *queue,
GList *link)
......@@ -108,6 +136,13 @@ g_queue_push_head_link (GQueue *queue,
queue->length++;
}
/**
* g_queue_push_tail:
* @queue: a #GQueue.
* @data: the data for the new element.
*
* Adds a new element at the tail of the queue.
**/
void
g_queue_push_tail (GQueue *queue,
gpointer data)
......@@ -122,6 +157,14 @@ g_queue_push_tail (GQueue *queue,
queue->length++;
}
/**
* g_queue_push_tail_link:
* @queue: a #GQueue.
* @link: a single #GList element, <emphasis>not</emphasis> a list with
* more than one element.
*
* Adds a new element at the tail of the queue.
**/
void
g_queue_push_tail_link (GQueue *queue,
GList *link)
......@@ -140,6 +183,15 @@ g_queue_push_tail_link (GQueue *queue,
queue->length++;
}
/**
* g_queue_pop_head:
* @queue: a #GQueue.
*
* Removes the first element of the queue.
*
* Returns: the data of the first element in the queue, or %NULL if the queue
* is empty.
**/
gpointer
g_queue_pop_head (GQueue *queue)
{
......@@ -164,6 +216,15 @@ g_queue_pop_head (GQueue *queue)
return NULL;
}
/**
* g_queue_pop_head_link:
* @queue: a #GQueue.
*
* Removes the first element of the queue.
*
* Returns: the #GList element at the head of the queue, or %NULL if the queue
* is empty.
**/
GList*
g_queue_pop_head_link (GQueue *queue)
{
......@@ -189,6 +250,15 @@ g_queue_pop_head_link (GQueue *queue)
return NULL;
}
/**
* g_queue_pop_tail:
* @queue: a #GQueue.
*
* Removes the last element of the queue.
*
* Returns: the data of the last element in the queue, or %NULL if the queue
* is empty.
**/
gpointer
g_queue_pop_tail (GQueue *queue)
{
......@@ -213,6 +283,15 @@ g_queue_pop_tail (GQueue *queue)
return NULL;
}
/**
* g_queue_pop_tail_link:
* @queue: a #GQueue.
*
* Removes the last element of the queue.
*
* Returns: the #GList element at the tail of the queue, or %NULL if the queue
* is empty.
**/
GList*
g_queue_pop_tail_link (GQueue *queue)
{
......@@ -238,6 +317,14 @@ g_queue_pop_tail_link (GQueue *queue)
return NULL;
}
/**
* g_queue_is_empty:
* @queue: a #GQueue.
*
* Returns %TRUE if the queue is empty.
*
* Returns: %TRUE if the queue is empty.
**/
gboolean
g_queue_is_empty (GQueue *queue)
{
......@@ -246,6 +333,15 @@ g_queue_is_empty (GQueue *queue)
return queue->head == NULL;
}
/**
* g_queue_peek_head:
* @queue: a #GQueue.
*
* Returns the first element of the queue.
*
* Returns: the data of the first element in the queue, or %NULL if the queue
* is empty.
**/
gpointer
g_queue_peek_head (GQueue *queue)
{
......@@ -254,6 +350,15 @@ g_queue_peek_head (GQueue *queue)
return queue->head ? queue->head->data : NULL;
}
/**
* g_queue_peek_tail:
* @queue: a #GQueue.
*
* Returns the last element of the queue.
*