[glib] documentation fixes
- From: Matthias Clasen <matthiasc src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [glib] documentation fixes
- Date: Wed, 14 Dec 2011 04:02:13 +0000 (UTC)
commit 7e92997539b481e31b5566b4885c8b5158488daa
Author: Stef Walter <stefw collabora co uk>
Date: Tue Dec 13 23:00:16 2011 -0500
documentation fixes
Fixes for gtk-doc warnings.
http://bugzilla.gnome.org/show_bug.cgi?id=66469
https://bugzilla.gnome.org/show_bug.cgi?id=664699
docs/reference/glib/glib-sections.txt | 4 ++
docs/reference/gobject/gobject-sections.txt | 2 +
glib/docs.c | 6 ++-
glib/garray.c | 12 +++---
glib/gbacktrace.h | 2 +-
glib/gerror.c | 2 +-
glib/gfileutils.c | 10 ++--
glib/ggettext.c | 2 +-
glib/ghook.c | 4 +-
glib/giochannel.c | 10 ++--
glib/glib-init.c | 2 +-
glib/glib-unix.c | 20 +++++----
glib/glib-unix.h | 4 +-
glib/gmain.c | 6 +-
glib/gmain.h | 3 +-
glib/gmessages.c | 6 +-
glib/gpoll.h | 3 +
glib/gscanner.c | 65 ++++++++++++++++++---------
glib/gscanner.h | 10 +++-
glib/gspawn.c | 8 ++--
glib/gspawn.h | 34 +++++++-------
glib/gstdio.c | 2 +-
glib/gstrfuncs.c | 54 +++++++++++-----------
glib/gtestutils.c | 12 +++---
glib/gthread-posix.c | 2 +-
glib/gthread.c | 8 ++--
gmodule/gmodule.c | 1 +
gobject/genums.c | 2 +-
28 files changed, 169 insertions(+), 127 deletions(-)
---
diff --git a/docs/reference/glib/glib-sections.txt b/docs/reference/glib/glib-sections.txt
index 1557258..bfe12c9 100644
--- a/docs/reference/glib/glib-sections.txt
+++ b/docs/reference/glib/glib-sections.txt
@@ -1853,6 +1853,7 @@ G_KEY_FILE_DESKTOP_TYPE_DIRECTORY
<SUBSECTION Private>
g_key_file_error_quark
+g_key_file_get_type
</SECTION>
<SECTION>
@@ -2416,6 +2417,9 @@ g_bytes_ref
g_bytes_unref
g_bytes_unref_to_data
g_bytes_unref_to_array
+
+<SUBSECTION Private>
+g_bytes_get_type
</SECTION>
<SECTION>
diff --git a/docs/reference/gobject/gobject-sections.txt b/docs/reference/gobject/gobject-sections.txt
index e466d57..2ed3cd8 100644
--- a/docs/reference/gobject/gobject-sections.txt
+++ b/docs/reference/gobject/gobject-sections.txt
@@ -506,6 +506,8 @@ GParamSpecChar
g_param_spec_char
g_value_set_char
g_value_get_char
+g_value_get_schar
+g_value_set_schar
<SUBSECTION guchar>
G_IS_PARAM_SPEC_UCHAR
diff --git a/glib/docs.c b/glib/docs.c
index 7616820..97d41cd 100644
--- a/glib/docs.c
+++ b/glib/docs.c
@@ -1456,6 +1456,7 @@
/**
* GFloatIEEE754:
+ * @v_float: the double value
*
* The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign,
* mantissa and exponent of IEEE floats and doubles. These unions are defined
@@ -1465,6 +1466,7 @@
/**
* GDoubleIEEE754:
+ * @v_double: the double value
*
* The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign,
* mantissa and exponent of IEEE floats and doubles. These unions are defined
@@ -1694,7 +1696,7 @@
/**
* G_CONST_RETURN:
*
- * If %G_DISABLE_CONST_RETURNS is defined, this macro expands
+ * If <literal>G_DISABLE_CONST_RETURNS</literal> is defined, this macro expands
* to nothing. By default, the macro expands to <literal>const</literal>.
* The macro should be used in place of <literal>const</literal> for
* functions that return a value that should not be modified. The
@@ -1735,7 +1737,7 @@
*
* This macro is used to export function prototypes so they can be linked
* with an external version when no inlining is performed. The file which
- * implements the functions should define %G_IMPLEMENTS_INLINES
+ * implements the functions should define <literal>G_IMPLEMENTS_INLINES</literal>
* before including the headers which contain %G_INLINE_FUNC declarations.
* Since inlining is very compiler-dependent using these macros correctly
* is very difficult. Their use is strongly discouraged.
diff --git a/glib/garray.c b/glib/garray.c
index f46656e..bddf28a 100644
--- a/glib/garray.c
+++ b/glib/garray.c
@@ -619,8 +619,8 @@ g_array_remove_range (GArray *farray,
* greater than second arg).
*
* If two array elements compare equal, their order in the sorted array
- * is undefined. If you want equal elements to keep their order – i.e.
- * you want a stable sort – you can write a comparison function that,
+ * is undefined. If you want equal elements to keep their order (i.e.
+ * you want a stable sort) you can write a comparison function that,
* if two elements would otherwise compare equal, compares them by
* their addresses.
**/
@@ -1272,8 +1272,8 @@ g_ptr_array_add (GPtrArray *farray,
* greater than second arg).
*
* If two array elements compare equal, their order in the sorted array
- * is undefined. If you want equal elements to keep their order – i.e.
- * you want a stable sort – you can write a comparison function that,
+ * is undefined. If you want equal elements to keep their order (i.e.
+ * you want a stable sort) you can write a comparison function that,
* if two elements would otherwise compare equal, compares them by
* their addresses.
*
@@ -1656,8 +1656,8 @@ g_byte_array_remove_range (GByteArray *array,
* first arg is greater than second arg).
*
* If two array elements compare equal, their order in the sorted array
- * is undefined. If you want equal elements to keep their order – i.e.
- * you want a stable sort – you can write a comparison function that,
+ * is undefined. If you want equal elements to keep their order (i.e.
+ * you want a stable sort) you can write a comparison function that,
* if two elements would otherwise compare equal, compares them by
* their addresses.
**/
diff --git a/glib/gbacktrace.h b/glib/gbacktrace.h
index f599432..f0a6eab 100644
--- a/glib/gbacktrace.h
+++ b/glib/gbacktrace.h
@@ -45,7 +45,7 @@ void g_on_error_stack_trace (const gchar *prg_name);
* Inserts a breakpoint instruction into the code.
*
* On x86 and alpha systems this is implemented as a soft interrupt
- * and on other architectures it raises a %SIGTRAP signal.
+ * and on other architectures it raises a <literal>SIGTRAP</literal> signal.
*/
#if (defined (__i386__) || defined (__x86_64__)) && defined (__GNUC__) && __GNUC__ >= 2
# define G_BREAKPOINT() G_STMT_START{ __asm__ __volatile__ ("int $03"); }G_STMT_END
diff --git a/glib/gerror.c b/glib/gerror.c
index 6217aa2..dc28cb2 100644
--- a/glib/gerror.c
+++ b/glib/gerror.c
@@ -281,7 +281,7 @@
* If there's a "generic" or "unknown" error code for unrecoverable
* errors it doesn't make sense to distinguish with specific codes,
* it should be called <literal><NAMESPACE>_<MODULE>_ERROR_FAILED</literal>,
- * for example %G_SPAWN_ERROR_FAILED or %G_THREAD_ERROR_FAILED.
+ * for example %G_SPAWN_ERROR_FAILED.
* </para></listitem>
* </itemizedlist>
*
diff --git a/glib/gfileutils.c b/glib/gfileutils.c
index f5c8db2..9b603a5 100644
--- a/glib/gfileutils.c
+++ b/glib/gfileutils.c
@@ -109,7 +109,7 @@
* not correctly attached to the computer.
* @G_FILE_ERROR_NODEV: The underlying file system of the specified file
* does not support memory mapping.
- * G_FILE_ERROR_ROFS: The directory containing the new link can't be
+ * @G_FILE_ERROR_ROFS: The directory containing the new link can't be
* modified because it's on a read-only file system.
* @G_FILE_ERROR_TXTBSY: Text file busy.
* @G_FILE_ERROR_FAULT: You passed in a pointer to bad memory.
@@ -310,7 +310,7 @@ g_mkdir_with_parents (const gchar *pathname,
* %G_FILE_TEST_IS_SYMLINK will always return %FALSE. Testing for
* %G_FILE_TEST_IS_EXECUTABLE will just check that the file exists and
* its name indicates that it is executable, checking for well-known
- * extensions and those listed in the %PATHEXT environment variable.
+ * extensions and those listed in the <envar>PATHEXT</envar> environment variable.
*
* Return value: whether a test was %TRUE
**/
@@ -469,9 +469,9 @@ g_file_error_quark (void)
* g_file_error_from_errno:
* @err_no: an "errno" value
*
- * Gets a #GFileError constant based on the passed-in @errno.
- * For example, if you pass in %EEXIST this function returns
- * #G_FILE_ERROR_EXIST. Unlike @errno values, you can portably
+ * Gets a #GFileError constant based on the passed-in @err_no.
+ * For example, if you pass in <literal>EEXIST</literal> this function returns
+ * #G_FILE_ERROR_EXIST. Unlike <literal>errno</literal> values, you can portably
* assume that all #GFileError values will exist.
*
* Normally a #GFileError value goes into a #GError returned
diff --git a/glib/ggettext.c b/glib/ggettext.c
index 0f1ebb1..7af37bf 100644
--- a/glib/ggettext.c
+++ b/glib/ggettext.c
@@ -407,7 +407,7 @@ g_dgettext (const gchar *domain,
* @category: a locale category
*
* This is a variant of g_dgettext() that allows specifying a locale
- * category instead of always using %LC_MESSAGES. See g_dgettext() for
+ * category instead of always using <envar>LC_MESSAGES</envar>. See g_dgettext() for
* more information about how this functions differs from calling
* dcgettext() directly.
*
diff --git a/glib/ghook.c b/glib/ghook.c
index 65b9421..93ea846 100644
--- a/glib/ghook.c
+++ b/glib/ghook.c
@@ -77,7 +77,7 @@
* @G_HOOK_FLAG_ACTIVE: set if the hook has not been destroyed
* @G_HOOK_FLAG_IN_CALL: set if the hook is currently being run
* @G_HOOK_FLAG_MASK: A mask covering all bits reserved for
- * hook flags; see #G_HOOK_FLAGS_USER_SHIFT
+ * hook flags; see %G_HOOK_FLAG_USER_SHIFT
*
* Flags used internally in the #GHook implementation.
*/
@@ -86,7 +86,7 @@
* G_HOOK_FLAGS:
* @hook: a #GHook
*
- * Returns the flags of a hook.
+ * Gets the flags of a hook.
*/
/**
diff --git a/glib/giochannel.c b/glib/giochannel.c
index 38bd38a..f294701 100644
--- a/glib/giochannel.c
+++ b/glib/giochannel.c
@@ -752,7 +752,7 @@ g_io_channel_get_buffer_condition (GIOChannel *channel)
/**
* g_io_channel_error_from_errno:
- * @en: an <literal>errno</literal> error number, e.g. %EINVAL
+ * @en: an <literal>errno</literal> error number, e.g. <literal>EINVAL</literal>
*
* Converts an <literal>errno</literal> error number to a #GIOChannelError.
*
@@ -937,18 +937,18 @@ g_io_channel_get_line_term (GIOChannel *channel,
* @flags: the flags to set on the IO channel
* @error: A location to return an error of type #GIOChannelError
*
- * Sets the (writeable) flags in @channel to (@flags & %G_IO_CHANNEL_SET_MASK).
+ * Sets the (writeable) flags in @channel to (@flags & %G_IO_FLAG_SET_MASK).
*
* Return value: the status of the operation.
**/
/**
* GIOFlags:
- * @G_IO_FLAG_APPEND: turns on append mode, corresponds to %O_APPEND
+ * @G_IO_FLAG_APPEND: turns on append mode, corresponds to <literal>O_APPEND</literal>
* (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).
+ * <literal>O_NONBLOCK</literal>/<literal>O_NDELAY</literal>
+ * (see the documentation of the UNIX open() syscall).
* @G_IO_FLAG_IS_READABLE: indicates that the io channel is readable.
* This flag cannot be changed.
* @G_IO_FLAG_IS_WRITABLE: indicates that the io channel is writable.
diff --git a/glib/glib-init.c b/glib/glib-init.c
index f50793b..5442a97 100644
--- a/glib/glib-init.c
+++ b/glib/glib-init.c
@@ -34,7 +34,7 @@
* g_mem_gc_friendly:
*
* This variable is %TRUE if the <envar>G_DEBUG</envar> environment variable
- * includes the key <link linkend="G_DEBUG">gc-friendly</link>.
+ * includes the key <literal>gc-friendly</literal>.
*/
#ifdef ENABLE_GC_FRIENDLY_DEFAULT
gboolean g_mem_gc_friendly = TRUE;
diff --git a/glib/glib-unix.c b/glib/glib-unix.c
index 838d1e2..b26609a 100644
--- a/glib/glib-unix.c
+++ b/glib/glib-unix.c
@@ -70,12 +70,13 @@ g_unix_set_error_from_errno (GError **error,
* Similar to the UNIX pipe() call, but on modern systems like Linux
* uses the pipe2() system call, which atomically creates a pipe with
* the configured flags. The only supported flag currently is
- * %FD_CLOEXEC. If for example you want to configure %O_NONBLOCK,
- * that must still be done separately with fcntl().
+ * <literal>FD_CLOEXEC</literal>. If for example you want to configure
+ * <literal>O_NONBLOCK</literal>, that must still be done separately with
+ * fcntl().
*
- * <note>This function does *not* take %O_CLOEXEC, it takes
- * %FD_CLOEXEC as if for fcntl(); these are different on
- * Linux/glibc.</note>
+ * <note>This function does *not* take <literal>O_CLOEXEC</literal>, it takes
+ * <literal>FD_CLOEXEC</literal> as if for fcntl(); these are
+ * different on Linux/glibc.</note>
*
* Returns: %TRUE on success, %FALSE if not (and errno will be set).
*
@@ -134,8 +135,8 @@ g_unix_open_pipe (int *fds,
* @error: a #GError
*
* Control the non-blocking state of the given file descriptor,
- * according to @nonblock. On most systems this uses %O_NONBLOCK, but
- * on some older ones may use %O_NDELAY.
+ * according to @nonblock. On most systems this uses <literal>O_NONBLOCK</literal>, but
+ * on some older ones may use <literal>O_NDELAY</literal>.
*
* Returns: %TRUE if successful
*
@@ -184,12 +185,13 @@ g_unix_set_fd_nonblocking (gint fd,
* @signum: A signal number
*
* Create a #GSource that will be dispatched upon delivery of the UNIX
- * signal @signum. Currently only %SIGHUP, %SIGINT, and %SIGTERM can
+ * signal @signum. Currently only <literal>SIGHUP</literal>,
+ * <literal>SIGINT</literal>, and <literal>SIGTERM</literal> can
* be monitored. Note that unlike the UNIX default, all sources which
* have created a watch will be dispatched, regardless of which
* underlying thread invoked g_unix_signal_source_new().
*
- * For example, an effective use of this function is to handle SIGTERM
+ * For example, an effective use of this function is to handle <literal>SIGTERM</literal>
* cleanly; flushing any outstanding files, and then calling
* g_main_loop_quit (). It is not safe to do any of this a regular
* UNIX signal handler; your handler may be invoked while malloc() or
diff --git a/glib/glib-unix.h b/glib/glib-unix.h
index 7be37f0..0b3bec1 100644
--- a/glib/glib-unix.h
+++ b/glib/glib-unix.h
@@ -52,8 +52,8 @@ G_BEGIN_DECLS
* It is expected that most code will not look at %errno from these
* APIs. Important cases where one would want to differentiate between
* errors are already covered by existing cross-platform GLib API,
- * such as e.g. #GFile wrapping %ENOENT. However, it is provided for
- * completeness, at least.
+ * such as e.g. #GFile wrapping <literal>ENOENT</literal>. However, it is
+ * provided for completeness, at least.
*/
#define G_UNIX_ERROR (g_unix_error_quark())
diff --git a/glib/gmain.c b/glib/gmain.c
index 90269bb..60b4404 100644
--- a/glib/gmain.c
+++ b/glib/gmain.c
@@ -1995,13 +1995,13 @@ g_clock_win32_init (void)
*
* Queries the system monotonic time, if available.
*
- * On POSIX systems with clock_gettime() and %CLOCK_MONOTONIC this call
+ * On POSIX systems with clock_gettime() and <literal>CLOCK_MONOTONIC</literal> this call
* is a very shallow wrapper for that. Otherwise, we make a best effort
* that probably involves returning the wall clock time (with at least
* microsecond accuracy, subject to the limitations of the OS kernel).
*
- * It's important to note that POSIX %CLOCK_MONOTONIC does not count
- * time spent while the machine is suspended.
+ * It's important to note that POSIX <literal>CLOCK_MONOTONIC</literal> does
+ * not count time spent while the machine is suspended.
*
* On Windows, "limitations of the OS kernel" is a rather substantial
* statement. Depending on the configuration of the system, the wall
diff --git a/glib/gmain.h b/glib/gmain.h
index a1fdf36..e24d6f5 100644
--- a/glib/gmain.h
+++ b/glib/gmain.h
@@ -88,8 +88,6 @@ typedef struct _GSourceCallbackFuncs GSourceCallbackFuncs;
* callback function with @user_data and whatever additional parameters
* are needed for this type of event source.
* @finalize: Called when the source is finalized.
- * @closure_callback:
- * @closure_marshal:
*
* The <structname>GSourceFuncs</structname> struct contains a table of
* functions used to handle event sources in a generic manner.
@@ -200,6 +198,7 @@ struct _GSourceFuncs
gpointer user_data);
void (*finalize) (GSource *source); /* Can be NULL */
+ /*< private >*/
/* For use by g_source_set_closure */
GSourceFunc closure_callback;
GSourceDummyMarshal closure_marshal; /* Really is of type GClosureMarshal */
diff --git a/glib/gmessages.c b/glib/gmessages.c
index 726d9f2..7dafbf5 100644
--- a/glib/gmessages.c
+++ b/glib/gmessages.c
@@ -165,7 +165,7 @@
* A convenience function/macro to log a warning message.
*
* You can make warnings fatal at runtime by setting the
- * %G_DEBUG environment variable (see
+ * <envar>G_DEBUG</envar> environment variable (see
* <ulink url="glib-running.html">Running GLib Applications</ulink>).
*/
@@ -182,7 +182,7 @@
* example.
*
* You can also make critical warnings fatal at runtime by
- * setting the %G_DEBUG environment variable (see
+ * setting the <envar>G_DEBUG</envar> environment variable (see
* <ulink url="glib-running.html">Running GLib Applications</ulink>).
*/
@@ -379,7 +379,7 @@ g_log_domain_get_handler_L (GLogDomain *domain,
* %G_LOG_LEVEL_ERROR is always fatal.
*
* You can also make some message levels fatal at runtime by setting
- * the %G_DEBUG environment variable (see
+ * the <envar>G_DEBUG</envar> environment variable (see
* <ulink url="glib-running.html">Running GLib Applications</ulink>).
*
* Returns: the old fatal mask
diff --git a/glib/gpoll.h b/glib/gpoll.h
index cc79381..f28b758 100644
--- a/glib/gpoll.h
+++ b/glib/gpoll.h
@@ -86,6 +86,9 @@ typedef gint (*GPollFunc) (GPollFD *ufds,
* for writing you would use %G_IO_OUT | %G_IO_ERR.
* @revents: a bitwise combination of flags from #GIOCondition, returned
* from the poll() function to indicate which events occurred.
+ *
+ * Represents a file descriptor, which events to poll for, and which events
+ * occurred.
*/
struct _GPollFD
{
diff --git a/glib/gscanner.c b/glib/gscanner.c
index e7628f4..76de6c8 100644
--- a/glib/gscanner.c
+++ b/glib/gscanner.c
@@ -113,6 +113,20 @@
* @G_TOKEN_LEFT_PAREN: a '(' character
* @G_TOKEN_LEFT_CURLY: a '{' character
* @G_TOKEN_RIGHT_CURLY: a '}' character
+ * @G_TOKEN_RIGHT_PAREN: a ')' character
+ * @G_TOKEN_ERROR: an error occurred
+ * @G_TOKEN_CHAR: a character
+ * @G_TOKEN_BINARY: a binary integer
+ * @G_TOKEN_OCTAL: an octal integer
+ * @G_TOKEN_INT: an integer
+ * @G_TOKEN_HEX: a hex integer
+ * @G_TOKEN_FLOAT: a floating point number
+ * @G_TOKEN_STRING: a string
+ * @G_TOKEN_SYMBOL: a symbol
+ * @G_TOKEN_IDENTIFIER: an identifier
+ * @G_TOKEN_IDENTIFIER_NULL: a null identifier
+ * @G_TOKEN_COMMENT_SINGLE: one line comment
+ * @G_TOKEN_COMMENT_MULTI: multi line comment
*
* The possible types of token returned from each
* g_scanner_get_next_token() call.
@@ -120,6 +134,18 @@
/**
* GTokenValue:
+ * @v_symbol: token symbol value
+ * @v_identifier: token identifier value
+ * @v_binary: token binary integer value
+ * @v_octal: octal integer value
+ * @v_int: integer value
+ * @v_int64: 64-bit integer value
+ * @v_float: floating point value
+ * @v_hex: hex integer value
+ * @v_string: string value
+ * @v_comment: comment value
+ * @v_char: character value
+ * @v_error: error value
*
* A union holding the value of the token.
*/
@@ -136,17 +162,17 @@
* @G_ERR_FLOAT_MALFORMED: malformed floating point number
*
* The possible errors, used in the @v_error field
- * of #GTokenValue, when the token is a #G_TOKEN_ERROR.
+ * of #GTokenValue, when the token is a %G_TOKEN_ERROR.
*/
/**
* GScanner:
- * @user_data:
- * @max_parse_errors:
- * @parse_errors:
- * @input_name:
- * @qdata:
- * @config:
+ * @user_data: unused
+ * @max_parse_errors: unused
+ * @parse_errors: g_scanner_error() increments this field
+ * @input_name: name of input stream, featured by the default message handler
+ * @qdata: quarked data
+ * @config: link into the scanner configuration
* @token: token parsed by the last g_scanner_get_next_token()
* @value: value of the last token from g_scanner_get_next_token()
* @line: line number of the last token from g_scanner_get_next_token()
@@ -155,12 +181,7 @@
* @next_value: value of the last token from g_scanner_peek_next_token()
* @next_line: line number of the last token from g_scanner_peek_next_token()
* @next_position: char number of the last token from g_scanner_peek_next_token()
- * @symbol_table:
- * @input_fd:
- * @text:
- * @text_end:
- * @buffer:
- * @scope_id:
+ * @msg_handler: handler function for _warn and _error
*
* The data structure representing a lexical scanner.
*
@@ -206,7 +227,7 @@
* @scan_identifier_1char: specifies if single-character
* identifiers are recognized (the default is %FALSE).
* @scan_identifier_NULL: specifies if %NULL is reported as
- * #G_TOKEN_IDENTIFIER_NULL (the default is %FALSE).
+ * %G_TOKEN_IDENTIFIER_NULL (the default is %FALSE).
* @scan_symbols: specifies if symbols are recognized (the default
* is %TRUE).
* @scan_binary: specifies if binary numbers are recognized (the
@@ -225,19 +246,19 @@
* quotes (the default is %TRUE).
* @numbers_2_int: specifies if binary, octal and hexadecimal numbers
* are reported as #G_TOKEN_INT (the default is %TRUE).
- * @int_2_float: specifies if all numbers are reported as #G_TOKEN_FLOAT
+ * @int_2_float: specifies if all numbers are reported as %G_TOKEN_FLOAT
* (the default is %FALSE).
* @identifier_2_string: specifies if identifiers are reported as strings
* (the default is %FALSE).
* @char_2_token: specifies if characters are reported by setting
- * <literal>token = ch</literal> or as #G_TOKEN_CHAR (the default
+ * <literal>token = ch</literal> or as %G_TOKEN_CHAR (the default
* is %TRUE).
* @symbol_2_token: specifies if symbols are reported by setting
- * <literal>token = v_symbol</literal> or as #G_TOKEN_SYMBOL (the
+ * <literal>token = v_symbol</literal> or as %G_TOKEN_SYMBOL (the
* default is %FALSE).
* @scope_0_fallback: specifies if a symbol is searched for in the
* default scope in addition to the current scope (the default is %FALSE).
- * @store_int64:
+ * @store_int64: use value.v_int64 rather than v_int
*
* Specifies the #GScanner parser configuration. Most settings can
* be changed during the parsing phase and will affect the lexical
@@ -1269,12 +1290,12 @@ g_scanner_get_char (GScanner *scanner,
* @expected_token: the expected token
* @identifier_spec: a string describing how the scanner's user
* refers to identifiers (%NULL defaults to "identifier").
- * This is used if @expected_token is #G_TOKEN_IDENTIFIER or
- * #G_TOKEN_IDENTIFIER_NULL.
+ * This is used if @expected_token is %G_TOKEN_IDENTIFIER or
+ * %G_TOKEN_IDENTIFIER_NULL.
* @symbol_spec: a string describing how the scanner's user refers
* to symbols (%NULL defaults to "symbol"). This is used if
- * @expected_token is #G_TOKEN_SYMBOL or any token value greater
- * than #G_TOKEN_LAST.
+ * @expected_token is %G_TOKEN_SYMBOL or any token value greater
+ * than %G_TOKEN_LAST.
* @symbol_name: the name of the symbol, if the scanner's current
* token is a symbol.
* @message: a message string to output at the end of the
diff --git a/glib/gscanner.h b/glib/gscanner.h
index 2063db6..dd932f4 100644
--- a/glib/gscanner.h
+++ b/glib/gscanner.h
@@ -105,6 +105,8 @@ typedef enum
G_TOKEN_COMMENT_SINGLE,
G_TOKEN_COMMENT_MULTI,
+
+ /*< private >*/
G_TOKEN_LAST
} GTokenType;
@@ -161,6 +163,8 @@ struct _GScannerConfig
guint symbol_2_token : 1;
guint scope_0_fallback : 1; /* try scope 0 on lookups? */
guint store_int64 : 1; /* use value.v_int64 rather than v_int */
+
+ /*< private >*/
guint padding_dummy;
};
@@ -193,7 +197,8 @@ struct _GScanner
GTokenValue next_value;
guint next_line;
guint next_position;
-
+
+ /*< private >*/
/* to be considered private */
GHashTable *symbol_table;
gint input_fd;
@@ -201,7 +206,8 @@ struct _GScanner
const gchar *text_end;
gchar *buffer;
guint scope_id;
-
+
+ /*< public >*/
/* handler function for _warn and _error */
GScannerMsgFunc msg_handler;
};
diff --git a/glib/gspawn.c b/glib/gspawn.c
index 3aa6a9b..388b654 100644
--- a/glib/gspawn.c
+++ b/glib/gspawn.c
@@ -112,7 +112,7 @@ g_spawn_error_quark (void)
* <note><para>
* If you are writing a GTK+ application, and the program you
* are spawning is a graphical application, too, then you may
- * want to use gdk_spawn_on_screen() instead to ensure that
+ * want to use gdk_spawn_on_screen() instead to ensure that
* the spawned program opens its windows on the right screen.
* </para></note>
*
@@ -484,7 +484,7 @@ g_spawn_sync (const gchar *working_directory,
* will only be searched if you pass the %G_SPAWN_SEARCH_PATH flag.
* If the program name is not a full path and %G_SPAWN_SEARCH_PATH flag is not
* used, then the program will be run from the current directory (or
- * %working_directory, if specified); this might be unexpected or even
+ * @working_directory, if specified); this might be unexpected or even
* dangerous in some cases when the current directory is world-writable.
*
* On Windows, note that all the string or string vector arguments to
@@ -538,7 +538,7 @@ g_spawn_sync (const gchar *working_directory,
* call g_spawn_close_pid() on the @child_pid, in order to free
* resources which may be associated with the child process. (On Unix,
* using a child watch is equivalent to calling waitpid() or handling
- * the %SIGCHLD signal manually. On Windows, calling g_spawn_close_pid()
+ * the <literal>SIGCHLD</literal> signal manually. On Windows, calling g_spawn_close_pid()
* is equivalent to calling CloseHandle() on the process handle returned
* in @child_pid). See g_child_watch_add().
*
@@ -622,7 +622,7 @@ g_spawn_sync (const gchar *working_directory,
* <note><para>
* If you are writing a GTK+ application, and the program you
* are spawning is a graphical application, too, then you may
- * want to use gdk_spawn_on_screen_with_pipes() instead to ensure that
+ * want to use gdk_spawn_on_screen_with_pipes() instead to ensure that
* the spawned program opens its windows on the right screen.
* </para></note>
*
diff --git a/glib/gspawn.h b/glib/gspawn.h
index ace73d1..fe7785b 100644
--- a/glib/gspawn.h
+++ b/glib/gspawn.h
@@ -45,22 +45,22 @@ G_BEGIN_DECLS
* @G_SPAWN_ERROR_FORK: Fork failed due to lack of memory.
* @G_SPAWN_ERROR_READ: Read or select on pipes failed.
* @G_SPAWN_ERROR_CHDIR: Changing to working directory failed.
- * @G_SPAWN_ERROR_ACCES: execv() returned %EACCES.
- * @G_SPAWN_ERROR_PERM: execv() returned %EPERM.
- * @G_SPAWN_ERROR_2BIG: execv() returned %E2BIG.
- * @G_SPAWN_ERROR_NOEXEC: execv() returned %ENOEXEC.
- * @G_SPAWN_ERROR_NAMETOOLONG: execv() returned %ENAMETOOLONG.
- * @G_SPAWN_ERROR_NOENT: execv() returned %ENOENT.
- * @G_SPAWN_ERROR_NOMEM: execv() returned %ENOMEM.
- * @G_SPAWN_ERROR_NOTDIR: execv() returned %ENOTDIR.
- * @G_SPAWN_ERROR_LOOP: execv() returned %ELOOP.
- * @G_SPAWN_ERROR_TXTBUSY: execv() returned %ETXTBUSY.
- * @G_SPAWN_ERROR_IO: execv() returned %EIO.
- * @G_SPAWN_ERROR_NFILE: execv() returned %ENFILE.
- * @G_SPAWN_ERROR_MFILE: execv() returned %EMFILE.
- * @G_SPAWN_ERROR_INVAL: execv() returned %EINVAL.
- * @G_SPAWN_ERROR_ISDIR: execv() returned %EISDIR.
- * @G_SPAWN_ERROR_LIBBAD: execv() returned %ELIBBAD.
+ * @G_SPAWN_ERROR_ACCES: execv() returned <literal>EACCES</literal>
+ * @G_SPAWN_ERROR_PERM: execv() returned <literal>EPERM</literal>
+ * @G_SPAWN_ERROR_2BIG: execv() returned <literal>E2BIG</literal>
+ * @G_SPAWN_ERROR_NOEXEC: execv() returned <literal>ENOEXEC</literal>
+ * @G_SPAWN_ERROR_NAMETOOLONG: execv() returned <literal>ENAMETOOLONG</literal>
+ * @G_SPAWN_ERROR_NOENT: execv() returned <literal>ENOENT</literal>
+ * @G_SPAWN_ERROR_NOMEM: execv() returned <literal>ENOMEM</literal>
+ * @G_SPAWN_ERROR_NOTDIR: execv() returned <literal>ENOTDIR</literal>
+ * @G_SPAWN_ERROR_LOOP: execv() returned <literal>ELOOP</literal>
+ * @G_SPAWN_ERROR_TXTBUSY: execv() returned <literal>ETXTBUSY</literal>
+ * @G_SPAWN_ERROR_IO: execv() returned <literal>EIO</literal>
+ * @G_SPAWN_ERROR_NFILE: execv() returned <literal>ENFILE</literal>
+ * @G_SPAWN_ERROR_MFILE: execv() returned <literal>EMFILE</literal>
+ * @G_SPAWN_ERROR_INVAL: execv() returned <literal>EINVAL</literal>
+ * @G_SPAWN_ERROR_ISDIR: execv() returned <literal>EISDIR</literal>
+ * @G_SPAWN_ERROR_LIBBAD: execv() returned <literal>ELIBBAD</literal>
* @G_SPAWN_ERROR_FAILED: Some other fatal failure,
* <literal>error->message</literal> should explain.
*
@@ -125,7 +125,7 @@ typedef enum
* call malloc(), which includes POSIX functions such as setenv().
* If you need to set up the child environment differently from
* the parent, you should use g_get_environ(), g_environ_setenv(),
- * and g_environ_unsetev(), and then pass the complete environment
+ * and g_environ_unsetenv(), and then pass the complete environment
* list to the <literal>g_spawn...</literal> function.
*/
typedef void (* GSpawnChildSetupFunc) (gpointer user_data);
diff --git a/glib/gstdio.c b/glib/gstdio.c
index fb5a9fb..1908918 100644
--- a/glib/gstdio.c
+++ b/glib/gstdio.c
@@ -744,7 +744,7 @@ g_fopen (const gchar *filename,
*
* See your C library manual for more details about freopen().
*
- * Returns: A <type>FILE</type> pointer if the file was successfully
+ * Returns: A <literal>FILE</literal> pointer if the file was successfully
* opened, or %NULL if an error occurred.
*
* Since: 2.6
diff --git a/glib/gstrfuncs.c b/glib/gstrfuncs.c
index 1d5e371..7109930 100644
--- a/glib/gstrfuncs.c
+++ b/glib/gstrfuncs.c
@@ -100,7 +100,7 @@
* recognizes standard ASCII letters and ignores the locale,
* returning %FALSE for all non-ASCII characters. Also, unlike
* the standard library function, this takes a <type>char</type>,
- * not an <type>int</type>, so don't call it on %EOF, but no need to
+ * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
* cast to #guchar before passing a possibly non-ASCII character in.
*
* Returns: %TRUE if @c is an ASCII alphanumeric character
@@ -116,7 +116,7 @@
* recognizes standard ASCII letters and ignores the locale,
* returning %FALSE for all non-ASCII characters. Also, unlike
* the standard library function, this takes a <type>char</type>,
- * not an <type>int</type>, so don't call it on %EOF, but no need to
+ * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
* cast to #guchar before passing a possibly non-ASCII character in.
*
* Returns: %TRUE if @c is an ASCII alphabetic character
@@ -132,7 +132,7 @@
* recognizes standard ASCII control characters and ignores the
* locale, returning %FALSE for all non-ASCII characters. Also,
* unlike the standard library function, this takes a <type>char</type>,
- * not an <type>int</type>, so don't call it on %EOF, but no need to
+ * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
* cast to #guchar before passing a possibly non-ASCII character in.
*
* Returns: %TRUE if @c is an ASCII control character.
@@ -146,7 +146,7 @@
*
* Unlike the standard C library isdigit() function, this takes
* a <type>char</type>, not an <type>int</type>, so don't call it
- * on %EOF, but no need to cast to #guchar before passing a possibly
+ * on <literal>EOF</literal>, but no need to cast to #guchar before passing a possibly
* non-ASCII character in.
*
* Returns: %TRUE if @c is an ASCII digit.
@@ -162,7 +162,7 @@
* recognizes standard ASCII characters and ignores the locale,
* returning %FALSE for all non-ASCII characters. Also, unlike
* the standard library function, this takes a <type>char</type>,
- * not an <type>int</type>, so don't call it on %EOF, but no need
+ * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need
* to cast to #guchar before passing a possibly non-ASCII character in.
*
* Returns: %TRUE if @c is an ASCII printing character other than space.
@@ -178,7 +178,7 @@
* recognizes standard ASCII letters and ignores the locale,
* returning %FALSE for all non-ASCII characters. Also, unlike
* the standard library function, this takes a <type>char</type>,
- * not an <type>int</type>, so don't call it on %EOF, but no need
+ * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need
* to worry about casting to #guchar before passing a possibly
* non-ASCII character in.
*
@@ -195,7 +195,7 @@
* recognizes standard ASCII characters and ignores the locale,
* returning %FALSE for all non-ASCII characters. Also, unlike
* the standard library function, this takes a <type>char</type>,
- * not an <type>int</type>, so don't call it on %EOF, but no need
+ * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need
* to cast to #guchar before passing a possibly non-ASCII character in.
*
* Returns: %TRUE if @c is an ASCII printing character.
@@ -211,7 +211,7 @@
* recognizes standard ASCII letters and ignores the locale,
* returning %FALSE for all non-ASCII characters. Also, unlike
* the standard library function, this takes a <type>char</type>,
- * not an <type>int</type>, so don't call it on %EOF, but no need to
+ * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
* cast to #guchar before passing a possibly non-ASCII character in.
*
* Returns: %TRUE if @c is an ASCII punctuation character.
@@ -227,7 +227,7 @@
* recognizes standard ASCII white-space and ignores the locale,
* returning %FALSE for all non-ASCII characters. Also, unlike
* the standard library function, this takes a <type>char</type>,
- * not an <type>int</type>, so don't call it on %EOF, but no need to
+ * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
* cast to #guchar before passing a possibly non-ASCII character in.
*
* Returns: %TRUE if @c is an ASCII white-space character
@@ -243,7 +243,7 @@
* recognizes standard ASCII letters and ignores the locale,
* returning %FALSE for all non-ASCII characters. Also, unlike
* the standard library function, this takes a <type>char</type>,
- * not an <type>int</type>, so don't call it on %EOF, but no need to
+ * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
* worry about casting to #guchar before passing a possibly non-ASCII
* character in.
*
@@ -258,7 +258,7 @@
*
* Unlike the standard C library isxdigit() function, this takes
* a <type>char</type>, not an <type>int</type>, so don't call it
- * on %EOF, but no need to cast to #guchar before passing a
+ * on <literal>EOF</literal>, but no need to cast to #guchar before passing a
* possibly non-ASCII character in.
*
* Returns: %TRUE if @c is an ASCII hexadecimal-digit character.
@@ -669,12 +669,12 @@ g_strtod (const gchar *nptr,
* To convert from a #gdouble to a string in a locale-insensitive
* way, use g_ascii_dtostr().
*
- * If the correct value would cause overflow, plus or minus %HUGE_VAL
- * is returned (according to the sign of the value), and %ERANGE is
- * stored in %errno. If the correct value would cause underflow,
- * zero is returned and %ERANGE is stored in %errno.
+ * If the correct value would cause overflow, plus or minus <literal>HUGE_VAL</literal>
+ * is returned (according to the sign of the value), and <literal>ERANGE</literal> is
+ * stored in <literal>errno</literal>. If the correct value would cause underflow,
+ * zero is returned and <literal>ERANGE</literal> is stored in <literal>errno</literal>.
*
- * This function resets %errno before calling strtod() so that
+ * This function resets <literal>errno</literal> before calling strtod() so that
* you can reliably detect overflow and underflow.
*
* Return value: the #gdouble value.
@@ -1121,10 +1121,11 @@ g_parse_long_long (const gchar *nptr,
* locale-sensitive system strtoull() function.
*
* If the correct value would cause overflow, %G_MAXUINT64
- * is returned, and %ERANGE is stored in %errno. If the base is
- * outside the valid range, zero is returned, and %EINVAL is stored
- * in %errno. If the string conversion fails, zero is returned, and
- * @endptr returns @nptr (if @endptr is non-%NULL).
+ * is returned, and <literal>ERANGE</literal> is stored in <literal>errno</literal>.
+ * If the base is outside the valid range, zero is returned, and
+ * <literal>EINVAL</literal> is stored in <literal>errno</literal>.
+ * If the string conversion fails, zero is returned, and @endptr returns
+ * @nptr (if @endptr is non-%NULL).
*
* Return value: the #guint64 value or zero on error.
*
@@ -1167,10 +1168,11 @@ g_ascii_strtoull (const gchar *nptr,
* locale-sensitive system strtoll() function.
*
* If the correct value would cause overflow, %G_MAXINT64 or %G_MININT64
- * is returned, and %ERANGE is stored in %errno. If the base is
- * outside the valid range, zero is returned, and %EINVAL is stored
- * in %errno. If the string conversion fails, zero is returned, and
- * @endptr returns @nptr (if @endptr is non-%NULL).
+ * is returned, and <literal>ERANGE</literal> is stored in <literal>errno</literal>.
+ * If the base is outside the valid range, zero is returned, and
+ * <literal>EINVAL</literal> is stored in <literal>errno</literal>. If the
+ * string conversion fails, zero is returned, and @endptr returns @nptr
+ * (if @endptr is non-%NULL).
*
* Return value: the #gint64 value or zero on error.
*
@@ -1612,7 +1614,7 @@ g_strreverse (gchar *string)
* all non-ASCII characters unchanged, even if they are lower case
* letters in a particular character set. Also unlike the standard
* library function, this takes and returns a char, not an int, so
- * don't call it on %EOF but no need to worry about casting to #guchar
+ * don't call it on <literal>EOF</literal> but no need to worry about casting to #guchar
* before passing a possibly non-ASCII character in.
*
* Return value: the result of converting @c to lower case.
@@ -1636,7 +1638,7 @@ g_ascii_tolower (gchar c)
* all non-ASCII characters unchanged, even if they are upper case
* letters in a particular character set. Also unlike the standard
* library function, this takes and returns a char, not an int, so
- * don't call it on %EOF but no need to worry about casting to #guchar
+ * don't call it on <literal>EOF</literal> but no need to worry about casting to #guchar
* before passing a possibly non-ASCII character in.
*
* Return value: the result of converting @c to upper case.
diff --git a/glib/gtestutils.c b/glib/gtestutils.c
index d2bf682..ddc880a 100644
--- a/glib/gtestutils.c
+++ b/glib/gtestutils.c
@@ -260,7 +260,7 @@
* an error message is logged and the application is terminated.
*
* The macro can be turned off in final releases of code by defining
- * #G_DISABLE_ASSERT when compiling the application.
+ * <envar>G_DISABLE_ASSERT</envar> when compiling the application.
*/
/**
@@ -271,7 +271,7 @@
* application is terminated.
*
* The macro can be turned off in final releases of code by defining
- * #G_DISABLE_ASSERT when compiling the application.
+ * <envar>G_DISABLE_ASSERT</envar> when compiling the application.
*/
/**
@@ -1281,10 +1281,10 @@ g_test_run (void)
* Create a new #GTestCase, named @test_name, this API is fairly
* low level, calling g_test_add() or g_test_add_func() is preferable.
* When this test is executed, a fixture structure of size @data_size
- * will be allocated and filled with 0s. Then data_setup() is called
+ * will be allocated and filled with 0s. Then @data_setup is called
* to initialize the fixture. After fixture setup, the actual test
- * function data_test() is called. Once the test run completed, the
- * fixture structure is torn down by calling data_teardown() and
+ * function @data_test is called. Once the test run completed, the
+ * fixture structure is torn down by calling @data_teardown and
* after that the memory is released.
*
* Splitting up a test run into fixture setup, test function and
@@ -1557,7 +1557,7 @@ g_test_queue_free (gpointer gfree_pointer)
* @destroy_func: Destroy callback for teardown phase.
* @destroy_data: Destroy callback data.
*
- * This function enqueus a callback @destroy_func() to be executed
+ * This function enqueus a callback @destroy_func to be executed
* during the next test case teardown phase. This is most useful
* to auto destruct allocted test resources at the end of a test run.
* Resources are released in reverse queue order, that means enqueueing
diff --git a/glib/gthread-posix.c b/glib/gthread-posix.c
index 8b7372f..79f5034 100644
--- a/glib/gthread-posix.c
+++ b/glib/gthread-posix.c
@@ -388,7 +388,7 @@ g_rec_mutex_lock (GRecMutex *mutex)
/**
* g_rec_mutex_unlock:
- * @rec_mutex: a #RecGMutex
+ * @rec_mutex: a #GRecMutex
*
* Unlocks @rec_mutex. If another thread is blocked in a
* g_rec_mutex_lock() call for @rec_mutex, it will become unblocked
diff --git a/glib/gthread.c b/glib/gthread.c
index d956308..c1d06ec 100644
--- a/glib/gthread.c
+++ b/glib/gthread.c
@@ -97,7 +97,7 @@
* Note that it is not safe to assume that your program has no threads
* even if you don't call g_thread_new() yourself. GLib and GIO can
* and will create threads for their own purposes in some cases, such
- * as when using g_unix_signal_source_new() or when using #GDBus.
+ * as when using g_unix_signal_source_new() or when using GDBus.
*
* Originally, UNIX did not have threads, and therefore some traditional
* UNIX APIs are problematic in threaded programs. Some notable examples
@@ -158,7 +158,7 @@
* G_LOCK_DEFINE:
* @name: the name of the lock
*
- * The %G_LOCK_* macros provide a convenient interface to #GMutex.
+ * The <literal>G_LOCK_*</literal> macros provide a convenient interface to #GMutex.
* #G_LOCK_DEFINE defines a lock. It can appear in any place where
* variable definitions may appear in programs, i.e. in the first block
* of a function or outside of functions. The @name parameter will be
@@ -166,10 +166,10 @@
* can use names of existing variables as the parameter - e.g. the name
* of the variable you intend to protect with the lock. Look at our
* <function>give_me_next_number()</function> example using the
- * %G_LOCK_* macros:
+ * <literal>G_LOCK_*</literal> macros:
*
* <example>
- * <title>Using the %G_LOCK_* convenience macros</title>
+ * <title>Using the <literal>G_LOCK_*</literal> convenience macros</title>
* <programlisting>
* G_LOCK_DEFINE (current_number);
*
diff --git a/gmodule/gmodule.c b/gmodule/gmodule.c
index f1933a7..22db6d0 100644
--- a/gmodule/gmodule.c
+++ b/gmodule/gmodule.c
@@ -132,6 +132,7 @@
/**
* GModule:
+ *
* The #GModule struct is an opaque data structure to represent a
* <link linkend="glib-Dynamic-Loading-of-Modules">Dynamically-Loaded
* Module</link>. It should only be accessed via the following functions.
diff --git a/gobject/genums.c b/gobject/genums.c
index c69af76..1b3411f 100644
--- a/gobject/genums.c
+++ b/gobject/genums.c
@@ -260,7 +260,7 @@ g_flags_register_static (const gchar *name,
* enumeration values. The array is terminated by a struct with all
* members being 0.
*
- * This function is meant to be called from the complete_type_info()
+ * This function is meant to be called from the <literal>complete_type_info</literal>
* function of a #GTypePlugin implementation, as in the following
* example:
*
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
