diff --git a/gio/gapplicationcommandline.c b/gio/gapplicationcommandline.c index 905b35e2c..badd995a0 100644 --- a/gio/gapplicationcommandline.c +++ b/gio/gapplicationcommandline.c @@ -132,8 +132,8 @@ /** * GApplicationCommandLineClass: * - * The GApplicationCommandLineClass 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 a9c99b2aa..a942374a0 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 GByteArray struct allows access to the - * public fields of a GByteArray. - **/ + * 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 410e00a96..397ec6b1f 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 struct timeval 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 - * GDate 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 time_t. It has been deprecated - * since it is not equivalent to time_t - * on 64-bit platforms with a 64-bit time_t. - * Unrelated to #GTimer. + * Simply a replacement for time_t. It has been deprecated + * since it is not 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. Instead, do the following: + * 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. + * + * 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 struct tm from - * @tm: struct tm to fill + * @date: a #GDate to set the struct tm from + * @tm: struct tm to fill * - * Fills in the date-related bits of a struct tm - * 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 93ea846bc..249a16010 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 GHookList 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 GHook 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 c638086ce..c06fef3cd 100644 --- a/glib/gpattern.c +++ b/glib/gpattern.c @@ -56,10 +56,9 @@ /** * GPatternSpec: * - * A GPatternSpec 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 fb2a8ec5b..aa9501c9b 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 - * GRand and GRandom. + * 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 * g_rand*_int_range() will have a slightly better * equal distribution with the new version of GLib. * diff --git a/glib/gstdio.c b/glib/gstdio.c index dfb3feb1c..28e1f68fe 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 stat 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 - * 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". + * 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 stat 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 FILE struct, the - * FILE 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 - * FILE 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 FILE 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 FILE 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 71eca13e5..71bac8df6 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 GTrashStack*. + * is cast to a GTrashStack*. */ /** diff --git a/glib/gtree.c b/glib/gtree.c index 46d780484..d5883304e 100644 --- a/glib/gtree.c +++ b/glib/gtree.c @@ -73,10 +73,9 @@ typedef struct _GTreeNode GTreeNode; /** * GTree: * - * The GTree struct is an opaque data - * structure representing a Balanced Binary Tree. It - * should be accessed only by using the following functions. + * The #GTree-struct is an opaque data structure representing a Balanced Binary Tree. + * It should be accessed only by using the following functions. */ struct _GTree { diff --git a/gmodule/gmodule.c b/gmodule/gmodule.c index 25d22a525..b1f2117d0 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(). * * - * Calling a function defined in a <structname>GModule</structname> + * Calling a function defined in a GModule * * /* the function signature for 'say_hello' */ * typedef void (* SayHelloFunc) (const char *message); diff --git a/gobject/gtype.c b/gobject/gtype.c index 098e81624..c8d355248 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 - * MyObjectPrivate to an object - * MyObject 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(). *