GNOME.org
 

[glib] Docs: don't use the structname tag

commit 3d42934b71f9e3e8ac82b00982a6e0b00ba1b92a
Author: Matthias Clasen <mclasen redhat com>
Date:   Fri Jan 31 00:29:14 2014 -0500

    Docs: don't use the structname tag
    
    Just avoid explicit docbook markup.

 gio/gapplicationcommandline.c |    4 +-
 glib/garray.c                 |    6 +-
 glib/gdate.c                  |   50 +++++++++++++------------
 glib/ghook.c                  |    6 +--
 glib/gpattern.c               |    7 +--
 glib/grand.c                  |    5 +-
 glib/gstdio.c                 |   83 ++++++++++++++++++++---------------------
 glib/gtrashstack.c            |    2 +-
 glib/gtree.c                  |    7 +--
 gmodule/gmodule.c             |    2 +-
 gobject/gtype.c               |    7 +--
 11 files changed, 86 insertions(+), 93 deletions(-)
---
diff --git a/gio/gapplicationcommandline.c b/gio/gapplicationcommandline.c
index 905b35e..badd995 100644
--- a/gio/gapplicationcommandline.c
+++ b/gio/gapplicationcommandline.c
@@ -132,8 +132,8 @@
 /**
  * GApplicationCommandLineClass:
  *
- * The <structname>GApplicationCommandLineClass</structname> structure
- * contains private data only
+ * The #GApplicationCommandLineClass-struct 
+ * contains private data only.
  *
  * Since: 2.28
  **/
diff --git a/glib/garray.c b/glib/garray.c
index a9c99b2..a942374 100644
--- a/glib/garray.c
+++ b/glib/garray.c
@@ -1547,9 +1547,9 @@ g_ptr_array_foreach (GPtrArray *array,
  *        elements are added to the #GByteArray.
  * @len: the number of elements in the #GByteArray.
  *
- * The <structname>GByteArray</structname> struct allows access to the
- * public fields of a <structname>GByteArray</structname>.
- **/
+ * The #GByteArray-struct allows access to the public fields of
+ * a #GByteArray.
+ */
 
 /**
  * g_byte_array_new:
diff --git a/glib/gdate.c b/glib/gdate.c
index 410e00a..397ec6b 100644
--- a/glib/gdate.c
+++ b/glib/gdate.c
@@ -117,8 +117,8 @@
  * @tv_usec: microseconds
  *
  * Represents a precise time, with seconds and microseconds.
- * Similar to the <structname>struct timeval</structname> returned by
- * the gettimeofday() UNIX system call.
+ * Similar to the struct timeval returned by the gettimeofday()
+ * UNIX system call.
  *
  * GLib is attempting to unify around the use of 64bit integers to
  * represent microsecond-precision time. As such, this type will be
@@ -137,29 +137,32 @@
  * @year: the day of the day-month-year representation of the date
  *
  * Represents a day between January 1, Year 1 and a few thousand years in
- * the future. None of its members should be accessed directly. If the
- * <structname>GDate</structname> is obtained from g_date_new(), it will
- * be safe to mutate but invalid and thus not safe for calendrical
- * computations. If it's declared on the stack, it will contain garbage
- * so must be initialized with g_date_clear(). g_date_clear() makes the
- * date invalid but sane. An invalid date doesn't represent a day, it's
- * "empty." A date becomes valid after you set it to a Julian day or you
- * set a day, month, and year.
+ * the future. None of its members should be accessed directly.
+ *
+ * If the #GDate-struct is obtained from g_date_new(), it will be safe
+ * to mutate but invalid and thus not safe for calendrical computations.
+ *
+ * If it's declared on the stack, it will contain garbage so must be
+ * initialized with g_date_clear(). g_date_clear() makes the date invalid
+ * but sane. An invalid date doesn't represent a day, it's "empty." A date
+ * becomes valid after you set it to a Julian day or you set a day, month,
+ * and year.
  */
 
 /**
  * GTime:
  *
- * Simply a replacement for <type>time_t</type>. It has been deprecated
- * since it is <emphasis>not</emphasis> equivalent to <type>time_t</type>
- * on 64-bit platforms with a 64-bit <type>time_t</type>.
- * Unrelated to #GTimer.
+ * Simply a replacement for time_t. It has been deprecated
+ * since it is <emphasis>not</emphasis> equivalent to time_t
+ * on 64-bit platforms with a 64-bit time_t. Unrelated to #GTimer.
+ *
+ * Note that #GTime is defined to always be a 32bit integer,
+ * unlike time_t which may be 64bit on some systems. Therefore,
+ * #GTime will overflow in the year 2038, and you cannot use the
+ * address of a #GTime variable as argument to the UNIX time()
+ * function.
  *
- * Note that <type>GTime</type> is defined to always be a 32bit integer,
- * unlike <type>time_t</type> which may be 64bit on some systems.
- * Therefore, <type>GTime</type> will overflow in the year 2038, and
- * you cannot use the address of a <type>GTime</type> variable as argument
- * to the UNIX time() function. Instead, do the following:
+ * Instead, do the following:
  * |[
  * time_t ttime;
  * GTime gtime;
@@ -1936,12 +1939,11 @@ g_date_compare (const GDate *lhs,
 
 /**
  * g_date_to_struct_tm:
- * @date: a #GDate to set the <structname>struct tm</structname> from
- * @tm: <structname>struct tm</structname> to fill
+ * @date: a #GDate to set the struct tm from
+ * @tm: struct tm to fill
  *
- * Fills in the date-related bits of a <structname>struct tm</structname>
- * using the @date value. Initializes the non-date parts with something
- * sane but meaningless.
+ * Fills in the date-related bits of a struct tm using the @date value.
+ * Initializes the non-date parts with something sane but meaningless.
  */
 void        
 g_date_to_struct_tm (const GDate *d, 
diff --git a/glib/ghook.c b/glib/ghook.c
index 93ea846..249a160 100644
--- a/glib/ghook.c
+++ b/glib/ghook.c
@@ -59,8 +59,7 @@
  *     The default behaviour is to call the hooks @destroy function
  * @dummy: unused
  *
- * The <structname>GHookList</structname> struct represents a
- * list of hook functions.
+ * The #GHookList-struct represents a list of hook functions.
  */
 
 /**
@@ -157,8 +156,7 @@
  * @destroy: the default @finalize_hook function of a #GHookList calls
  *     this member of the hook that is being finalized
  *
- * The <structname>GHook</structname> struct represents a single hook
- * function in a #GHookList.
+ * The #GHook-struct represents a single hook function in a #GHookList.
  */
 
 /**
diff --git a/glib/gpattern.c b/glib/gpattern.c
index c638086..c06fef3 100644
--- a/glib/gpattern.c
+++ b/glib/gpattern.c
@@ -56,10 +56,9 @@
 /**
  * GPatternSpec:
  *
- * A <structname>GPatternSpec</structname> is the 'compiled' form of a
- * pattern. This structure is opaque and its fields cannot be accessed
- * directly.
- **/
+ * A #GPatternSpec-struct is the 'compiled' form of a pattern. This
+ * structure is opaque and its fields cannot be accessed directly.
+ */
 
 /* keep enum and structure of gpattern.c and patterntest.c in sync */
 typedef enum
diff --git a/glib/grand.c b/glib/grand.c
index fb2a8ec..aa9501c 100644
--- a/glib/grand.c
+++ b/glib/grand.c
@@ -101,10 +101,9 @@
  * doesn't yield equally distributed numbers.
  *
  * GLib changed the seeding algorithm for the pseudo-random number
- * generator Mersenne Twister, as used by
- * <structname>GRand</structname> and <structname>GRandom</structname>.
+ * generator Mersenne Twister, as used by #GRand and #GRandom.
  * This was necessary, because some seeds would yield very bad
- * pseudo-random streams.  Also the pseudo-random integers generated by
+ * pseudo-random streams. Also the pseudo-random integers generated by
  * <function>g_rand*_int_range()</function> will have a slightly better
  * equal distribution with the new version of GLib.
  *
diff --git a/glib/gstdio.c b/glib/gstdio.c
index dfb3feb..28e1f68 100644
--- a/glib/gstdio.c
+++ b/glib/gstdio.c
@@ -74,8 +74,8 @@
  * See your C library manual for more details about access().
  *
  * Returns: zero if the pathname refers to an existing file system
- * object that has all the tested permissions, or -1 otherwise or on
- * error.
+ *     object that has all the tested permissions, or -1 otherwise
+ *     or on error.
  * 
  * Since: 2.8
  */
@@ -126,7 +126,7 @@ g_access (const gchar *filename,
  *
  * See your C library manual for more details about chmod().
  *
- * Returns: zero if the operation succeeded, -1 on error.
+ * Returns: 0 if the operation succeeded, -1 on error
  * 
  * Since: 2.8
  */
@@ -181,8 +181,9 @@ g_chmod (const gchar *filename,
  *
  * See your C library manual for more details about open().
  *
- * Returns: a new file descriptor, or -1 if an error occurred. The
- * return value can be used exactly like the return value from open().
+ * Returns: a new file descriptor, or -1 if an error occurred.
+ *     The return value can be used exactly like the return value
+ *     from open().
  * 
  * Since: 2.6
  */
@@ -243,8 +244,9 @@ g_open (const gchar *filename,
  *
  * See your C library manual for more details about creat().
  *
- * Returns: a new file descriptor, or -1 if an error occurred. The
- * return value can be used exactly like the return value from creat().
+ * Returns: a new file descriptor, or -1 if an error occurred.
+ *     The return value can be used exactly like the return value
+ *     from creat().
  * 
  * Since: 2.8
  */
@@ -432,41 +434,40 @@ g_chdir (const gchar *path)
 /**
  * GStatBuf:
  *
- * A type corresponding to the appropriate struct type for the stat
+ * A type corresponding to the appropriate struct type for the stat()
  * system call, depending on the platform and/or compiler being used.
  *
  * See g_stat() for more information.
- **/
+ */
 /**
  * g_stat: 
  * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
- * @buf: a pointer to a <structname>stat</structname> struct, which
- *    will be filled with the file information
+ * @buf: a pointer to a stat struct, which will be filled with the file
+ *     information
  *
  * A wrapper for the POSIX stat() function. The stat() function
  * returns information about a file. On Windows the stat() function in
  * the C library checks only the FAT-style READONLY attribute and does
  * not look at the ACL at all. Thus on Windows the protection bits in
- * the st_mode field are a fabrication of little use.
+ * the @st_mode field are a fabrication of little use.
  * 
  * On Windows the Microsoft C libraries have several variants of the
- * <structname>stat</structname> struct and stat() function with names
- * like "_stat", "_stat32", "_stat32i64" and "_stat64i32". The one
- * used here is for 32-bit code the one with 32-bit size and time
- * fields, specifically called "_stat32".
+ * stat struct and stat() function with names like _stat(), _stat32(),
+ * _stat32i64() and _stat64i32(). The one used here is for 32-bit code
+ * the one with 32-bit size and time fields, specifically called _stat32().
  *
- * In Microsoft's compiler, by default "struct stat" means one with
- * 64-bit time fields while in MinGW "struct stat" is the legacy one
+ * In Microsoft's compiler, by default struct stat means one with
+ * 64-bit time fields while in MinGW struct stat is the legacy one
  * with 32-bit fields. To hopefully clear up this messs, the gstdio.h
- * header defines a type GStatBuf which is the appropriate struct type
+ * header defines a type #GStatBuf which is the appropriate struct type
  * depending on the platform and/or compiler being used. On POSIX it
- * is just "struct stat", but note that even on POSIX platforms,
- * "stat" might be a macro.
+ * is just struct stat, but note that even on POSIX platforms, stat()
+ * might be a macro.
  *
  * See your C library manual for more details about stat().
  *
- * Returns: 0 if the information was successfully retrieved, -1 if an error 
- *    occurred
+ * Returns: 0 if the information was successfully retrieved,
+ *     -1 if an error occurred
  * 
  * Since: 2.6
  */
@@ -508,8 +509,8 @@ g_stat (const gchar *filename,
 /**
  * g_lstat: 
  * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
- * @buf: a pointer to a <structname>stat</structname> struct, which
- *    will be filled with the file information
+ * @buf: a pointer to a stat struct, which will be filled with the file
+ *     information
  *
  * A wrapper for the POSIX lstat() function. The lstat() function is
  * like stat() except that in the case of symbolic links, it returns
@@ -519,8 +520,8 @@ g_stat (const gchar *filename,
  * 
  * See your C library manual for more details about lstat().
  *
- * Returns: 0 if the information was successfully retrieved, -1 if an error 
- *    occurred
+ * Returns: 0 if the information was successfully retrieved,
+ *     -1 if an error occurred
  * 
  * Since: 2.6
  */
@@ -678,24 +679,22 @@ g_rmdir (const gchar *filename)
 /**
  * g_fopen:
  * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
- * @mode: a string describing the mode in which the file should be 
- *   opened
+ * @mode: a string describing the mode in which the file should be opened
  *
  * A wrapper for the stdio fopen() function. The fopen() function
  * opens a file and associates a new stream with it.
  * 
  * Because file descriptors are specific to the C library on Windows,
- * and a file descriptor is partof the <type>FILE</type> struct, the
- * <type>FILE</type> pointer returned by this function makes sense
- * only to functions in the same C library. Thus if the GLib-using
- * code uses a different C library than GLib does, the
- * <type>FILE</type> pointer returned by this function cannot be
- * passed to C library functions like fprintf() or fread().
+ * and a file descriptor is part of the FILE struct, the FILE* returned
+ * by this function makes sense only to functions in the same C library.
+ * Thus if the GLib-using code uses a different C library than GLib does,
+ * the FILE* returned by this function cannot be passed to C library
+ * functions like fprintf() or fread().
  *
  * See your C library manual for more details about fopen().
  *
- * Returns: A <type>FILE</type> pointer if the file was successfully
- *    opened, or %NULL if an error occurred
+ * Returns: A FILE* if the file was successfully opened, or %NULL if
+ *     an error occurred
  * 
  * Since: 2.6
  */
@@ -740,8 +739,7 @@ g_fopen (const gchar *filename,
 /**
  * g_freopen:
  * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
- * @mode: a string describing the mode in which the file should be 
- *   opened
+ * @mode: a string describing the mode in which the file should be  opened
  * @stream: (allow-none): an existing stream which will be reused, or %NULL
  *
  * A wrapper for the POSIX freopen() function. The freopen() function
@@ -749,8 +747,8 @@ g_fopen (const gchar *filename,
  * 
  * See your C library manual for more details about freopen().
  *
- * Returns: A <literal>FILE</literal> pointer if the file was successfully
- *    opened, or %NULL if an error occurred.
+ * Returns: A FILE* if the file was successfully opened, or %NULL if
+ *     an error occurred.
  * 
  * Since: 2.6
  */
@@ -804,8 +802,7 @@ g_freopen (const gchar *filename,
  * See your C library manual for more details about how utime() works
  * on your system.
  *
- * Returns: 0 if the operation was successful, -1 if an error 
- *    occurred
+ * Returns: 0 if the operation was successful, -1 if an error occurred
  * 
  * Since: 2.18
  */
diff --git a/glib/gtrashstack.c b/glib/gtrashstack.c
index 71eca13..71bac8d 100644
--- a/glib/gtrashstack.c
+++ b/glib/gtrashstack.c
@@ -47,7 +47,7 @@
  *     bytes of the element
  *
  * Each piece of memory that is pushed onto the stack
- * is cast to a <structname>GTrashStack*</structname>.
+ * is cast to a GTrashStack*.
  */
 
 /**
diff --git a/glib/gtree.c b/glib/gtree.c
index 46d7804..d588330 100644
--- a/glib/gtree.c
+++ b/glib/gtree.c
@@ -73,10 +73,9 @@ typedef struct _GTreeNode  GTreeNode;
 /**
  * GTree:
  *
- * The <structname>GTree</structname> struct is an opaque data
- * structure representing a <link
- * linkend="glib-Balanced-Binary-Trees">Balanced Binary Tree</link>. It
- * should be accessed only by using the following functions.
+ * The #GTree-struct is an opaque data structure representing a <link
+ * linkend="glib-Balanced-Binary-Trees">Balanced Binary Tree</link>.
+ * It should be accessed only by using the following functions.
  */
 struct _GTree
 {
diff --git a/gmodule/gmodule.c b/gmodule/gmodule.c
index 25d22a5..b1f2117 100644
--- a/gmodule/gmodule.c
+++ b/gmodule/gmodule.c
@@ -82,7 +82,7 @@
  * it must ensure that it is never unloaded, by calling g_module_make_resident().
  *
  * <example>
- * <title>Calling a function defined in a <structname>GModule</structname></title>
+ * <title>Calling a function defined in a GModule</title>
  * <programlisting>
  * /&ast; the function signature for 'say_hello' &ast;/
  * typedef void (* SayHelloFunc) (const char *message);
diff --git a/gobject/gtype.c b/gobject/gtype.c
index 098e816..c8d3552 100644
--- a/gobject/gtype.c
+++ b/gobject/gtype.c
@@ -4422,10 +4422,9 @@ gobject_init_ctor (void)
  * G_TYPE_INSTANCE_GET_PRIVATE() macro.
  *
  * The following example shows attaching a private structure
- * <structname>MyObjectPrivate</structname> to an object
- * <structname>MyObject</structname> defined in the standard GObject
- * fashion.
- * type's class_init() function.
+ * MyObjectPrivate to an object MyObject defined in the standard
+ * GObject fashion in the type's class_init() function.
+ *
  * Note the use of a structure member "priv" to avoid the overhead
  * of repeatedly calling MY_OBJECT_GET_PRIVATE().
  *
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]