[glib] Fix some glib docs warnings
- From: Ryan Lortie <ryanl src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [glib] Fix some glib docs warnings
- Date: Mon, 12 Jul 2010 20:56:55 +0000 (UTC)
commit 7791fce38a1a7d292e94d3bb5a0ffb8d6da9333d
Author: Ryan Lortie <desrt desrt ca>
Date: Mon Jul 12 16:37:56 2010 -0400
Fix some glib docs warnings
Remove some symbols from glib-sections.txt that gtk-doc has no idea
about.
Add proper callback typedefs for GTester (gtk-doc dislikes inline
function types).
Fix some other minor issues.
docs/reference/glib/glib-sections.txt | 9 +++-
docs/reference/glib/tmpl/fileutils.sgml | 6 +++
docs/reference/glib/tmpl/testing.sgml | 35 +++++++++++++++--
glib/gstdio.c | 8 ++++
glib/gstrfuncs.c | 10 ++--
glib/gtestutils.c | 62 ++++++++++++++++++++++--------
glib/gtestutils.h | 30 +++++++++------
glib/gutf8.c | 2 +-
glib/gvariant.c | 2 +-
9 files changed, 121 insertions(+), 43 deletions(-)
---
diff --git a/docs/reference/glib/glib-sections.txt b/docs/reference/glib/glib-sections.txt
index 628b5e4..da95251 100644
--- a/docs/reference/glib/glib-sections.txt
+++ b/docs/reference/glib/glib-sections.txt
@@ -1168,6 +1168,7 @@ g_mapped_file_get_contents
g_open
g_rename
g_mkdir
+GStatBuf
g_stat
g_lstat
g_unlink
@@ -1399,7 +1400,6 @@ g_date_sunday_week_of_year
g_date_days_in_month
g_date_monday_weeks_in_year
g_date_sunday_weeks_in_year
-tm
</SECTION>
<SECTION>
@@ -2654,7 +2654,9 @@ g_test_perf
g_test_verbose
g_test_quiet
g_test_run
+GTestFunc
g_test_add_func
+GTestDataFunc
g_test_add_data_func
g_test_add
@@ -2701,6 +2703,7 @@ g_assert_error
GTestCase
GTestSuite
+GTestFixtureFunc
g_test_create_case
g_test_create_suite
g_test_get_root
@@ -2718,7 +2721,6 @@ g_assertion_message_error
g_test_add_vtable
GTestConfig
-g_test_config_vars
GTestLogType
GTestLogMsg
GTestLogBuffer
@@ -2757,6 +2759,9 @@ G_VARIANT_TYPE_TUPLE
G_VARIANT_TYPE_UNIT
G_VARIANT_TYPE_DICT_ENTRY
G_VARIANT_TYPE_DICTIONARY
+G_VARIANT_TYPE_STRING_ARRAY
+G_VARIANT_TYPE_BYTESTRING
+G_VARIANT_TYPE_BYTESTRING_ARRAY
<SUBSECTION>
G_VARIANT_TYPE
diff --git a/docs/reference/glib/tmpl/fileutils.sgml b/docs/reference/glib/tmpl/fileutils.sgml
index b99430b..7b65df6 100644
--- a/docs/reference/glib/tmpl/fileutils.sgml
+++ b/docs/reference/glib/tmpl/fileutils.sgml
@@ -382,6 +382,12 @@ not be accessed directly.
@Returns:
+<!-- ##### TYPEDEF GStatBuf ##### -->
+<para>
+
+</para>
+
+
<!-- ##### FUNCTION g_stat ##### -->
<para>
diff --git a/docs/reference/glib/tmpl/testing.sgml b/docs/reference/glib/tmpl/testing.sgml
index 477c88d..af7c3ca 100644
--- a/docs/reference/glib/tmpl/testing.sgml
+++ b/docs/reference/glib/tmpl/testing.sgml
@@ -150,13 +150,29 @@ Returns %TRUE if tests are run in quiet mode.
@Returns:
+<!-- ##### USER_FUNCTION GTestFunc ##### -->
+<para>
+
+</para>
+
+ void:
+
+
<!-- ##### FUNCTION g_test_add_func ##### -->
<para>
</para>
@testpath:
- void:
+ test_func:
+
+
+<!-- ##### USER_FUNCTION GTestDataFunc ##### -->
+<para>
+
+</para>
+
+ user_data:
<!-- ##### FUNCTION g_test_add_data_func ##### -->
@@ -166,7 +182,7 @@ Returns %TRUE if tests are run in quiet mode.
@testpath:
@test_data:
- gconstpointer:
+ test_func:
<!-- ##### MACRO g_test_add ##### -->
@@ -597,6 +613,15 @@ An opaque structure representing a test suite.
</para>
+<!-- ##### USER_FUNCTION GTestFixtureFunc ##### -->
+<para>
+
+</para>
+
+ fixture:
+ user_data:
+
+
<!-- ##### FUNCTION g_test_create_case ##### -->
<para>
@@ -605,9 +630,9 @@ An opaque structure representing a test suite.
@test_name:
@data_size:
@test_data:
- void:
- void:
- void:
+ data_setup:
+ data_test:
+ data_teardown:
@Returns:
diff --git a/glib/gstdio.c b/glib/gstdio.c
index 54c2164..a2cd277 100644
--- a/glib/gstdio.c
+++ b/glib/gstdio.c
@@ -426,6 +426,14 @@ g_chdir (const gchar *path)
}
/**
+ * GStatBuf:
+ *
+ * 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
diff --git a/glib/gstrfuncs.c b/glib/gstrfuncs.c
index 67f1947..d7e82d1 100644
--- a/glib/gstrfuncs.c
+++ b/glib/gstrfuncs.c
@@ -1664,10 +1664,10 @@ g_strlcpy (gchar *dest,
* strcat() or strncat(), but for real security g_strconcat() is harder
* to mess up.</para></note>
*
- * Returns size of attempted result, which is
- * MIN (dest_size, strlen (original dest)) + strlen (src),
- * so if retval >= dest_size, truncation occurred.
- */
+ * Returns: size of attempted result, which is MIN (dest_size, strlen
+ * (original dest)) + strlen (src), so if retval >= dest_size,
+ * truncation occurred.
+ **/
gsize
g_strlcat (gchar *dest,
const gchar *src,
@@ -3216,7 +3216,7 @@ g_dgettext (const gchar *domain,
}
/**
- * g_dgettext:
+ * g_dcgettext:
* @domain: (allow-none): the translation domain to use, or %NULL to use
* the domain set with textdomain()
* @msgid: message to translate
diff --git a/glib/gtestutils.c b/glib/gtestutils.c
index 80fc3ea..c5754ec 100644
--- a/glib/gtestutils.c
+++ b/glib/gtestutils.c
@@ -906,12 +906,12 @@ g_test_run (void)
* Since: 2.16
*/
GTestCase*
-g_test_create_case (const char *test_name,
- gsize data_size,
- gconstpointer test_data,
- void (*data_setup) (void),
- void (*data_test) (void),
- void (*data_teardown) (void))
+g_test_create_case (const char *test_name,
+ gsize data_size,
+ gconstpointer test_data,
+ GTestFixtureFunc data_setup,
+ GTestFixtureFunc data_test,
+ GTestFixtureFunc data_teardown)
{
GTestCase *tc;
g_return_val_if_fail (test_name != NULL, NULL);
@@ -928,13 +928,29 @@ g_test_create_case (const char *test_name,
return tc;
}
+/**
+ * GTestFixtureFunc:
+ * @fixture: the test fixture
+ * @user_data: the data provided when registering the test
+ *
+ * The type used for functions that operate on test fixtures. This is
+ * used for the fixture setup and teardown functions as well as for the
+ * testcases themselves.
+ *
+ * @user_data is a pointer to the data that was given when registering
+ * the test case.
+ *
+ * @fixture will be a pointer to the area of memory allocated by the
+ * test framework, of the size requested. If the requested size was
+ * zero then @fixture will be equal to @user_data.
+ **/
void
-g_test_add_vtable (const char *testpath,
- gsize data_size,
- gconstpointer test_data,
- void (*data_setup) (void),
- void (*fixture_test_func) (void),
- void (*data_teardown) (void))
+g_test_add_vtable (const char *testpath,
+ gsize data_size,
+ gconstpointer test_data,
+ GTestFixtureFunc data_setup,
+ GTestFixtureFunc fixture_test_func,
+ GTestFixtureFunc data_teardown)
{
gchar **segments;
guint ui;
@@ -970,6 +986,11 @@ g_test_add_vtable (const char *testpath,
}
/**
+ * GTestFunc:
+ *
+ * The type used for test case functions.
+ **/
+/**
* g_test_add_func:
* @testpath: Slash-separated test case path name for the test.
* @test_func: The test function to invoke for this test.
@@ -982,16 +1003,23 @@ g_test_add_vtable (const char *testpath,
* Since: 2.16
*/
void
-g_test_add_func (const char *testpath,
- void (*test_func) (void))
+g_test_add_func (const char *testpath,
+ GTestFunc test_func)
{
g_return_if_fail (testpath != NULL);
g_return_if_fail (testpath[0] == '/');
g_return_if_fail (test_func != NULL);
- g_test_add_vtable (testpath, 0, NULL, NULL, test_func, NULL);
+ g_test_add_vtable (testpath, 0, NULL, NULL, (GTestFixtureFunc) test_func, NULL);
}
/**
+ * GTestDataFunc:
+ * @user_data: the data provided when registering the test
+ *
+ * The type used for test case functions that take an extra pointer
+ * argument.
+ **/
+/**
* g_test_add_data_func:
* @testpath: Slash-separated test case path name for the test.
* @test_data: Test data argument for the test function.
@@ -1008,12 +1036,12 @@ g_test_add_func (const char *testpath,
void
g_test_add_data_func (const char *testpath,
gconstpointer test_data,
- void (*test_func) (gconstpointer))
+ GTestDataFunc test_func)
{
g_return_if_fail (testpath != NULL);
g_return_if_fail (testpath[0] == '/');
g_return_if_fail (test_func != NULL);
- g_test_add_vtable (testpath, 0, test_data, NULL, (void(*)(void)) test_func, NULL);
+ g_test_add_vtable (testpath, 0, test_data, NULL, (GTestFixtureFunc) test_func, NULL);
}
/**
diff --git a/glib/gtestutils.h b/glib/gtestutils.h
index bfdf8cc..b441fe0 100644
--- a/glib/gtestutils.h
+++ b/glib/gtestutils.h
@@ -34,6 +34,10 @@ G_BEGIN_DECLS
typedef struct GTestCase GTestCase;
typedef struct GTestSuite GTestSuite;
+typedef void (*GTestFunc) (void);
+typedef void (*GTestDataFunc) (gconstpointer user_data);
+typedef void (*GTestFixtureFunc) (gpointer fixture,
+ gconstpointer user_data);
/* assertion API */
#define g_assert_cmpstr(s1, cmp, s2) do { const char *__s1 = (s1), *__s2 = (s2); \
@@ -98,10 +102,12 @@ void g_test_init (int *argc,
int g_test_run (void);
/* hook up a test functions under test path */
void g_test_add_func (const char *testpath,
- void (*test_func) (void));
+ GTestFunc test_func);
+
void g_test_add_data_func (const char *testpath,
gconstpointer test_data,
- void (*test_func) (gconstpointer));
+ GTestDataFunc test_func);
+
/* hook up a test with fixture under test path */
#define g_test_add(testpath, Fixture, tdata, fsetup, ftest, fteardown) \
G_STMT_START { \
@@ -158,13 +164,13 @@ double g_test_rand_double_range (double range_start,
double range_end);
/* semi-internal API */
-GTestCase* g_test_create_case (const char *test_name,
- gsize data_size,
- gconstpointer test_data,
- void (*data_setup) (void),
- void (*data_test) (void),
- void (*data_teardown) (void));
-GTestSuite* g_test_create_suite (const char *suite_name);
+GTestCase* g_test_create_case (const char *test_name,
+ gsize data_size,
+ gconstpointer test_data,
+ GTestFixtureFunc data_setup,
+ GTestFixtureFunc data_test,
+ GTestFixtureFunc data_teardown);
+GTestSuite* g_test_create_suite (const char *suite_name);
GTestSuite* g_test_get_root (void);
void g_test_suite_add (GTestSuite *suite,
GTestCase *test_case);
@@ -217,9 +223,9 @@ void g_assertion_message_error (const char *domain,
void g_test_add_vtable (const char *testpath,
gsize data_size,
gconstpointer test_data,
- void (*data_setup) (void),
- void (*data_test) (void),
- void (*data_teardown) (void));
+ GTestFixtureFunc data_setup,
+ GTestFixtureFunc data_test,
+ GTestFixtureFunc data_teardown);
typedef struct {
gboolean test_initialized;
gboolean test_quick; /* disable thorough tests */
diff --git a/glib/gutf8.c b/glib/gutf8.c
index 3d1d180..659400f 100644
--- a/glib/gutf8.c
+++ b/glib/gutf8.c
@@ -95,7 +95,7 @@
(Result) |= ((Chars)[(Count)] & 0x3f); \
}
-/**
+/*
* Check whether a Unicode (5.2) char is in a valid range.
*
* The first check comes from the Unicode guarantee to never encode
diff --git a/glib/gvariant.c b/glib/gvariant.c
index 2092b78..461ca21 100644
--- a/glib/gvariant.c
+++ b/glib/gvariant.c
@@ -1392,7 +1392,7 @@ g_variant_dup_bytestring (GVariant *value,
/**
* g_variant_new_bytestring_array:
- * @strv (array length=length): an array of strings
+ * @strv: (array length=length): an array of strings
* @length: the length of @strv, or -1
* @returns: a new floating #GVariant instance
*
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
