diff options
| -rw-r--r-- | gir/Everything-1.0-expected.gir | 44 | ||||
| -rw-r--r-- | gir/GIMarshallingTests-1.0-expected.gir | 2 | ||||
| -rw-r--r-- | gir/everything.c | 6 | ||||
| -rw-r--r-- | gir/gimarshallingtests.c | 139 | ||||
| -rw-r--r-- | giscanner/annotationparser.py | 149 | ||||
| -rw-r--r-- | tests/scanner/annotation-1.0-expected.gir | 73 | ||||
| -rw-r--r-- | tests/scanner/annotation-1.0-expected.tgir | 12 | ||||
| -rw-r--r-- | tests/scanner/annotation.c | 13 | ||||
| -rw-r--r-- | tests/scanner/annotation.h | 2 | ||||
| -rw-r--r-- | tests/scanner/foo-1.0-expected.gir | 18 |
10 files changed, 278 insertions, 180 deletions
diff --git a/gir/Everything-1.0-expected.gir b/gir/Everything-1.0-expected.gir index 3d3e4e88..36c1153c 100644 --- a/gir/Everything-1.0-expected.gir +++ b/gir/Everything-1.0-expected.gir @@ -245,7 +245,9 @@ case."> <type name="int" c:type="int"/> </return-value> <parameters> - <parameter name="somestr" transfer-ownership="none"> + <parameter name="somestr" + transfer-ownership="none" + doc="Meaningless string"> <type name="utf8" c:type="char*"/> </parameter> </parameters> @@ -346,7 +348,9 @@ case."> <type name="int" c:type="int"/> </return-value> <parameters> - <parameter name="somestr" transfer-ownership="none"> + <parameter name="somestr" + transfer-ownership="none" + doc="Meaningless string"> <type name="utf8" c:type="char*"/> </parameter> </parameters> @@ -428,7 +432,9 @@ case."> <parameter name="obj" transfer-ownership="none"> <type name="TestObj" c:type="TestObj*"/> </parameter> - <parameter name="somestr" transfer-ownership="none"> + <parameter name="somestr" + transfer-ownership="none" + doc="Meaningless string"> <type name="utf8" c:type="char*"/> </parameter> </parameters> @@ -655,7 +661,8 @@ case."> </function> <function name="test_array_fixed_size_int_in" c:identifier="test_array_fixed_size_int_in"> - <return-value transfer-ownership="none"> + <return-value transfer-ownership="none" + doc="the sum of the items in @ints"> <type name="int" c:type="int"/> </return-value> <parameters> @@ -755,7 +762,8 @@ case."> </parameters> </function> <function name="test_array_gtype_in" c:identifier="test_array_gtype_in"> - <return-value transfer-ownership="full"> + <return-value transfer-ownership="full" + doc="string representation of provided types"> <type name="utf8" c:type="char*"/> </return-value> <parameters> @@ -780,7 +788,8 @@ case."> <parameter name="len" direction="out" caller-allocates="0" - transfer-ownership="full"> + transfer-ownership="full" + doc="length of the returned array."> <type name="int" c:type="int*"/> </parameter> </parameters> @@ -851,7 +860,8 @@ case."> <parameter name="len" direction="out" caller-allocates="0" - transfer-ownership="full"> + transfer-ownership="full" + doc="length of the returned array."> <type name="int" c:type="int*"/> </parameter> </parameters> @@ -867,7 +877,7 @@ case."> <type name="int"/> </array> </parameter> - <parameter name="len" transfer-ownership="none"> + <parameter name="len" transfer-ownership="none" doc="length"> <type name="int" c:type="int"/> </parameter> </parameters> @@ -891,7 +901,7 @@ case."> direction="out" caller-allocates="0" transfer-ownership="full" - doc=": length"> + doc="length"> <type name="int" c:type="int*"/> </parameter> </parameters> @@ -1077,7 +1087,8 @@ is invoked."> doc="Invokes all callbacks installed by #test_callback_destroy_notify(), adding up their return values, and removes them, invoking the corresponding destroy notfications."> - <return-value transfer-ownership="none"> + <return-value transfer-ownership="none" + doc="Sum of the return values of the invoked callbacks."> <type name="int" c:type="int"/> </return-value> </function> @@ -1225,7 +1236,8 @@ call and can be released on return."> </parameters> </function> <function name="test_ghash_nested_everything_return" - c:identifier="test_ghash_nested_everything_return"> + c:identifier="test_ghash_nested_everything_return" + doc="Specify nested parameterized types directly with the (type ) annotation."> <return-value transfer-ownership="full"> <type name="GLib.HashTable" c:type="GHashTable*"> <type name="utf8"/> @@ -1237,7 +1249,8 @@ call and can be released on return."> </return-value> </function> <function name="test_ghash_nested_everything_return2" - c:identifier="test_ghash_nested_everything_return2"> + c:identifier="test_ghash_nested_everything_return2" + doc="element-type annotation."> <return-value transfer-ownership="full"> <type name="GLib.HashTable" c:type="GHashTable*"> <type name="utf8"/> @@ -2073,7 +2086,8 @@ call and can be released on return."> </function> <function name="test_utf8_const_return" c:identifier="test_utf8_const_return"> - <return-value transfer-ownership="none"> + <return-value transfer-ownership="none" + doc="<const char*> UTF-8 string"> <type name="utf8" c:type="char*"/> </return-value> </function> @@ -2103,7 +2117,7 @@ call and can be released on return."> </function> <function name="test_utf8_nonconst_return" c:identifier="test_utf8_nonconst_return"> - <return-value transfer-ownership="full"> + <return-value transfer-ownership="full" doc="<char*> UTF-8 string"> <type name="utf8" c:type="char*"/> </return-value> </function> @@ -2187,7 +2201,7 @@ call and can be released on return."> <type name="GObject.Value" c:type="GValue*"/> </return-value> <parameters> - <parameter name="i" transfer-ownership="none"> + <parameter name="i" transfer-ownership="none" doc="an int"> <type name="int" c:type="int"/> </parameter> </parameters> diff --git a/gir/GIMarshallingTests-1.0-expected.gir b/gir/GIMarshallingTests-1.0-expected.gir index b83dbdf6..4069d1eb 100644 --- a/gir/GIMarshallingTests-1.0-expected.gir +++ b/gir/GIMarshallingTests-1.0-expected.gir @@ -1903,7 +1903,7 @@ and/or use gtk-doc annotations. --> </function> <function name="gstrv_return" c:identifier="g_i_marshalling_tests_gstrv_return"> - <return-value transfer-ownership="full"> + <return-value transfer-ownership="full" doc="an array of strings"> <array c:type="GStrv"> <type name="utf8"/> </array> diff --git a/gir/everything.c b/gir/everything.c index 690dc733..2219667f 100644 --- a/gir/everything.c +++ b/gir/everything.c @@ -1094,7 +1094,7 @@ static /*const*/ GHashTable *test_table_ghash_const() /** * test_ghash_free: - * @in: (transfer full) (element-type utf8 utf8) + * @in: (transfer full) (element-type utf8 utf8): */ void test_ghash_free (GHashTable *in) { @@ -1840,7 +1840,7 @@ test_obj_do_matrix (TestObj *obj, const char *somestr) /** * test_object_null_in: - * @obj: (allow-none) A #TestObj + * @obj: (allow-none): A #TestObj */ void test_object_null_in (TestObj *obj) @@ -1849,7 +1849,7 @@ test_object_null_in (TestObj *obj) /** * test_object_null_out: - * @obj: (allow-none) (out) A #TestObj + * @obj: (allow-none) (out): A #TestObj */ void test_object_null_out (TestObj **obj) diff --git a/gir/gimarshallingtests.c b/gir/gimarshallingtests.c index da2fadec..f5f1a8c7 100644 --- a/gir/gimarshallingtests.c +++ b/gir/gimarshallingtests.c @@ -35,7 +35,7 @@ g_i_marshalling_tests_boolean_in_false (gboolean bool_) /** * g_i_marshalling_tests_boolean_out_true: - * bool_: (out): + * @bool_: (out): */ void g_i_marshalling_tests_boolean_out_true (gboolean *bool_) @@ -45,7 +45,7 @@ g_i_marshalling_tests_boolean_out_true (gboolean *bool_) /** * g_i_marshalling_tests_boolean_out_false: - * bool_: (out): + * @bool_: (out): */ void g_i_marshalling_tests_boolean_out_false (gboolean *bool_) @@ -55,7 +55,7 @@ g_i_marshalling_tests_boolean_out_false (gboolean *bool_) /** * g_i_marshalling_tests_boolean_inout_true_false: - * bool_: (inout): + * @bool_: (inout): */ void g_i_marshalling_tests_boolean_inout_true_false (gboolean *bool_) @@ -66,7 +66,7 @@ g_i_marshalling_tests_boolean_inout_true_false (gboolean *bool_) /** * g_i_marshalling_tests_boolean_inout_false_true: - * bool_: (inout): + * @bool_: (inout): */ void g_i_marshalling_tests_boolean_inout_false_true (gboolean *bool_) @@ -104,7 +104,7 @@ g_i_marshalling_tests_int8_in_min (gint8 int8) /** * g_i_marshalling_tests_int8_out_max: - * int8: (out): + * @int8: (out): */ void g_i_marshalling_tests_int8_out_max (gint8 *int8) @@ -114,7 +114,7 @@ g_i_marshalling_tests_int8_out_max (gint8 *int8) /** * g_i_marshalling_tests_int8_out_min: - * int8: (out): + * @int8: (out): */ void g_i_marshalling_tests_int8_out_min (gint8 *int8) @@ -124,7 +124,7 @@ g_i_marshalling_tests_int8_out_min (gint8 *int8) /** * g_i_marshalling_tests_int8_inout_max_min: - * int8: (inout): + * @int8: (inout): */ void g_i_marshalling_tests_int8_inout_max_min (gint8 *int8) @@ -135,7 +135,7 @@ g_i_marshalling_tests_int8_inout_max_min (gint8 *int8) /** * g_i_marshalling_tests_int8_inout_min_max: - * int8: (inout): + * @int8: (inout): */ void g_i_marshalling_tests_int8_inout_min_max (gint8 *int8) @@ -159,7 +159,7 @@ g_i_marshalling_tests_uint8_in (guint8 uint8) /** * g_i_marshalling_tests_uint8_out: - * uint8: (out): + * @uint8: (out): */ void g_i_marshalling_tests_uint8_out (guint8 *uint8) @@ -169,7 +169,7 @@ g_i_marshalling_tests_uint8_out (guint8 *uint8) /** * g_i_marshalling_tests_uint8_inout: - * uint8: (inout): + * @uint8: (inout): */ void g_i_marshalling_tests_uint8_inout (guint8 *uint8) @@ -205,7 +205,7 @@ g_i_marshalling_tests_int16_in_min (gint16 int16) /** * g_i_marshalling_tests_int16_out_max: - * int16: (out): + * @int16: (out): */ void g_i_marshalling_tests_int16_out_max (gint16 *int16) @@ -215,7 +215,7 @@ g_i_marshalling_tests_int16_out_max (gint16 *int16) /** * g_i_marshalling_tests_int16_out_min: - * int16: (out): + * @int16: (out): */ void g_i_marshalling_tests_int16_out_min (gint16 *int16) @@ -225,7 +225,7 @@ g_i_marshalling_tests_int16_out_min (gint16 *int16) /** * g_i_marshalling_tests_int16_inout_max_min: - * int16: (inout): + * @int16: (inout): */ void g_i_marshalling_tests_int16_inout_max_min (gint16 *int16) @@ -236,7 +236,7 @@ g_i_marshalling_tests_int16_inout_max_min (gint16 *int16) /** * g_i_marshalling_tests_int16_inout_min_max: - * int16: (inout): + * @int16: (inout): */ void g_i_marshalling_tests_int16_inout_min_max (gint16 *int16) @@ -260,7 +260,7 @@ g_i_marshalling_tests_uint16_in (guint16 uint16) /** * g_i_marshalling_tests_uint16_out: - * uint16: (out): + * @uint16: (out): */ void g_i_marshalling_tests_uint16_out (guint16 *uint16) @@ -270,7 +270,7 @@ g_i_marshalling_tests_uint16_out (guint16 *uint16) /** * g_i_marshalling_tests_uint16_inout: - * uint16: (inout): + * @uint16: (inout): */ void g_i_marshalling_tests_uint16_inout (guint16 *uint16) @@ -306,7 +306,7 @@ g_i_marshalling_tests_int32_in_min (gint32 int32) /** * g_i_marshalling_tests_int32_out_max: - * int32: (out): + * @int32: (out): */ void g_i_marshalling_tests_int32_out_max (gint32 *int32) @@ -316,7 +316,7 @@ g_i_marshalling_tests_int32_out_max (gint32 *int32) /** * g_i_marshalling_tests_int32_out_min: - * int32: (out): + * @int32: (out): */ void g_i_marshalling_tests_int32_out_min (gint32 *int32) @@ -326,7 +326,7 @@ g_i_marshalling_tests_int32_out_min (gint32 *int32) /** * g_i_marshalling_tests_int32_inout_max_min: - * int32: (inout): + * @int32: (inout): */ void g_i_marshalling_tests_int32_inout_max_min (gint32 *int32) @@ -337,7 +337,7 @@ g_i_marshalling_tests_int32_inout_max_min (gint32 *int32) /** * g_i_marshalling_tests_int32_inout_min_max: - * int32: (inout): + * @int32: (inout): */ void g_i_marshalling_tests_int32_inout_min_max (gint32 *int32) @@ -361,7 +361,7 @@ g_i_marshalling_tests_uint32_in (guint32 uint32) /** * g_i_marshalling_tests_uint32_out: - * uint32: (out): + * @uint32: (out): */ void g_i_marshalling_tests_uint32_out (guint32 *uint32) @@ -371,7 +371,7 @@ g_i_marshalling_tests_uint32_out (guint32 *uint32) /** * g_i_marshalling_tests_uint32_inout: - * uint32: (inout): + * @uint32: (inout): */ void g_i_marshalling_tests_uint32_inout (guint32 *uint32) @@ -407,7 +407,7 @@ g_i_marshalling_tests_int64_in_min (gint64 int64) /** * g_i_marshalling_tests_int64_out_max: - * int64: (out): + * @int64: (out): */ void g_i_marshalling_tests_int64_out_max (gint64 *int64) @@ -417,7 +417,7 @@ g_i_marshalling_tests_int64_out_max (gint64 *int64) /** * g_i_marshalling_tests_int64_out_min: - * int64: (out): + * @int64: (out): */ void g_i_marshalling_tests_int64_out_min (gint64 *int64) @@ -427,7 +427,7 @@ g_i_marshalling_tests_int64_out_min (gint64 *int64) /** * g_i_marshalling_tests_int64_inout_max_min: - * int64: (inout): + * @int64: (inout): */ void g_i_marshalling_tests_int64_inout_max_min (gint64 *int64) @@ -438,7 +438,7 @@ g_i_marshalling_tests_int64_inout_max_min (gint64 *int64) /** * g_i_marshalling_tests_int64_inout_min_max: - * int64: (inout): + * @int64: (inout): */ void g_i_marshalling_tests_int64_inout_min_max (gint64 *int64) @@ -462,7 +462,7 @@ g_i_marshalling_tests_uint64_in (guint64 uint64) /** * g_i_marshalling_tests_uint64_out: - * uint64: (out): + * @uint64: (out): */ void g_i_marshalling_tests_uint64_out (guint64 *uint64) @@ -472,7 +472,7 @@ g_i_marshalling_tests_uint64_out (guint64 *uint64) /** * g_i_marshalling_tests_uint64_inout: - * uint64: (inout): + * @uint64: (inout): */ void g_i_marshalling_tests_uint64_inout (guint64 *uint64) @@ -508,7 +508,7 @@ g_i_marshalling_tests_short_in_min (gshort short_) /** * g_i_marshalling_tests_short_out_max: - * short_: (out): + * @short_: (out): */ void g_i_marshalling_tests_short_out_max (gshort *short_) @@ -518,7 +518,7 @@ g_i_marshalling_tests_short_out_max (gshort *short_) /** * g_i_marshalling_tests_short_out_min: - * short_: (out): + * @short_: (out): */ void g_i_marshalling_tests_short_out_min (gshort *short_) @@ -528,7 +528,7 @@ g_i_marshalling_tests_short_out_min (gshort *short_) /** * g_i_marshalling_tests_short_inout_max_min: - * short_: (inout): + * @short_: (inout): */ void g_i_marshalling_tests_short_inout_max_min (gshort *short_) @@ -539,7 +539,7 @@ g_i_marshalling_tests_short_inout_max_min (gshort *short_) /** * g_i_marshalling_tests_short_inout_min_max: - * short_: (inout): + * @short_: (inout): */ void g_i_marshalling_tests_short_inout_min_max (gshort *short_) @@ -563,7 +563,7 @@ g_i_marshalling_tests_ushort_in (gushort ushort) /** * g_i_marshalling_tests_ushort_out: - * ushort: (out): + * @ushort: (out): */ void g_i_marshalling_tests_ushort_out (gushort *ushort) @@ -573,7 +573,7 @@ g_i_marshalling_tests_ushort_out (gushort *ushort) /** * g_i_marshalling_tests_ushort_inout: - * ushort: (inout): + * @ushort: (inout): */ void g_i_marshalling_tests_ushort_inout (gushort *ushort) @@ -609,7 +609,7 @@ g_i_marshalling_tests_int_in_min (gint int_) /** * g_i_marshalling_tests_int_out_max: - * int_: (out): + * @int_: (out): */ void g_i_marshalling_tests_int_out_max (gint *int_) @@ -619,7 +619,7 @@ g_i_marshalling_tests_int_out_max (gint *int_) /** * g_i_marshalling_tests_int_out_min: - * int_: (out): + * @int_: (out): */ void g_i_marshalling_tests_int_out_min (gint *int_) @@ -629,7 +629,7 @@ g_i_marshalling_tests_int_out_min (gint *int_) /** * g_i_marshalling_tests_int_inout_max_min: - * int_: (inout): + * @int_: (inout): */ void g_i_marshalling_tests_int_inout_max_min (gint *int_) @@ -640,7 +640,7 @@ g_i_marshalling_tests_int_inout_max_min (gint *int_) /** * g_i_marshalling_tests_int_inout_min_max: - * int_: (inout): + * @int_: (inout): */ void g_i_marshalling_tests_int_inout_min_max (gint *int_) @@ -664,7 +664,7 @@ g_i_marshalling_tests_uint_in (guint uint) /** * g_i_marshalling_tests_uint_out: - * uint: (out): + * @uint: (out): */ void g_i_marshalling_tests_uint_out (guint *uint) @@ -674,7 +674,7 @@ g_i_marshalling_tests_uint_out (guint *uint) /** * g_i_marshalling_tests_uint_inout: - * uint: (inout): + * @uint: (inout): */ void g_i_marshalling_tests_uint_inout (guint *uint) @@ -710,7 +710,7 @@ g_i_marshalling_tests_long_in_min (glong long_) /** * g_i_marshalling_tests_long_out_max: - * long_: (out): + * @long_: (out): */ void g_i_marshalling_tests_long_out_max (glong *long_) @@ -720,7 +720,7 @@ g_i_marshalling_tests_long_out_max (glong *long_) /** * g_i_marshalling_tests_long_out_min: - * long_: (out): + * @long_: (out): */ void g_i_marshalling_tests_long_out_min (glong *long_) @@ -730,7 +730,7 @@ g_i_marshalling_tests_long_out_min (glong *long_) /** * g_i_marshalling_tests_long_inout_max_min: - * long_: (inout): + * @long_: (inout): */ void g_i_marshalling_tests_long_inout_max_min (glong *long_) @@ -741,7 +741,7 @@ g_i_marshalling_tests_long_inout_max_min (glong *long_) /** * g_i_marshalling_tests_long_inout_min_max: - * long_: (inout): + * @long_: (inout): */ void g_i_marshalling_tests_long_inout_min_max (glong *long_) @@ -765,7 +765,7 @@ g_i_marshalling_tests_ulong_in (gulong ulong) /** * g_i_marshalling_tests_ulong_out: - * ulong: (out): + * @ulong: (out): */ void g_i_marshalling_tests_ulong_out (gulong *ulong) @@ -775,7 +775,7 @@ g_i_marshalling_tests_ulong_out (gulong *ulong) /** * g_i_marshalling_tests_ulong_inout: - * ulong: (inout): + * @ulong: (inout): */ void g_i_marshalling_tests_ulong_inout (gulong *ulong) @@ -811,7 +811,7 @@ g_i_marshalling_tests_ssize_in_min (gssize ssize) /** * g_i_marshalling_tests_ssize_out_max: - * ssize: (out): + * @ssize: (out): */ void g_i_marshalling_tests_ssize_out_max (gssize *ssize) @@ -821,7 +821,7 @@ g_i_marshalling_tests_ssize_out_max (gssize *ssize) /** * g_i_marshalling_tests_ssize_out_min: - * ssize: (out): + * @ssize: (out): */ void g_i_marshalling_tests_ssize_out_min (gssize *ssize) @@ -831,7 +831,7 @@ g_i_marshalling_tests_ssize_out_min (gssize *ssize) /** * g_i_marshalling_tests_ssize_inout_max_min: - * ssize: (inout): + * @ssize: (inout): */ void g_i_marshalling_tests_ssize_inout_max_min (gssize *ssize) @@ -842,7 +842,7 @@ g_i_marshalling_tests_ssize_inout_max_min (gssize *ssize) /** * g_i_marshalling_tests_ssize_inout_min_max: - * ssize: (inout): + * @ssize: (inout): */ void g_i_marshalling_tests_ssize_inout_min_max (gssize *ssize) @@ -866,7 +866,7 @@ g_i_marshalling_tests_size_in (gsize size) /** * g_i_marshalling_tests_size_out: - * size: (out): + * @size: (out): */ void g_i_marshalling_tests_size_out (gsize *size) @@ -876,7 +876,7 @@ g_i_marshalling_tests_size_out (gsize *size) /** * g_i_marshalling_tests_size_inout: - * size: (inout): + * @size: (inout): */ void g_i_marshalling_tests_size_inout (gsize *size) @@ -900,7 +900,7 @@ g_i_marshalling_tests_float_in (gfloat float_) /** * g_i_marshalling_tests_float_out: - * float_: (out): + * @float_: (out): */ void g_i_marshalling_tests_float_out (gfloat *float_) @@ -910,7 +910,7 @@ g_i_marshalling_tests_float_out (gfloat *float_) /** * g_i_marshalling_tests_float_inout: - * float_: (inout): + * @float_: (inout): */ void g_i_marshalling_tests_float_inout (gfloat *float_) @@ -934,7 +934,7 @@ g_i_marshalling_tests_double_in (gdouble double_) /** * g_i_marshalling_tests_double_out: - * double_: (out): + * @double_: (out): */ void g_i_marshalling_tests_double_out (gdouble *double_) @@ -944,7 +944,7 @@ g_i_marshalling_tests_double_out (gdouble *double_) /** * g_i_marshalling_tests_double_inout: - * double_: (inout): + * @double_: (inout): */ void g_i_marshalling_tests_double_inout (gdouble *double_) @@ -968,7 +968,7 @@ g_i_marshalling_tests_time_t_in (time_t time_t_) /** * g_i_marshalling_tests_time_t_out: - * time_t_: (out): + * @time_t_: (out): */ void g_i_marshalling_tests_time_t_out (time_t *time_t_) @@ -978,7 +978,7 @@ g_i_marshalling_tests_time_t_out (time_t *time_t_) /** * g_i_marshalling_tests_time_t_inout: - * time_t_: (inout): + * @time_t_: (inout): */ void g_i_marshalling_tests_time_t_inout (time_t *time_t_) @@ -1002,7 +1002,7 @@ g_i_marshalling_tests_gtype_in (GType gtype) /** * g_i_marshalling_tests_gtype_out: - * gtype: (out): + * @gtype: (out): */ void g_i_marshalling_tests_gtype_out (GType *gtype) @@ -1012,7 +1012,7 @@ g_i_marshalling_tests_gtype_out (GType *gtype) /** * g_i_marshalling_tests_gtype_inout: - * gtype: (inout): + * @gtype: (inout): */ void g_i_marshalling_tests_gtype_inout (GType *gtype) @@ -1049,7 +1049,7 @@ g_i_marshalling_tests_utf8_full_in (gchar *utf8) /** * g_i_marshalling_tests_utf8_none_out: - * utf8: (out) (transfer none): + * @utf8: (out) (transfer none): */ void g_i_marshalling_tests_utf8_none_out (gchar **utf8) @@ -1059,7 +1059,7 @@ g_i_marshalling_tests_utf8_none_out (gchar **utf8) /** * g_i_marshalling_tests_utf8_full_out: - * utf8: (out) (transfer full): + * @utf8: (out) (transfer full): */ void g_i_marshalling_tests_utf8_full_out (gchar **utf8) @@ -1069,7 +1069,7 @@ g_i_marshalling_tests_utf8_full_out (gchar **utf8) /** * g_i_marshalling_tests_utf8_dangling_out: - * utf8: (out) (transfer full): + * @utf8: (out) (transfer full): */ void g_i_marshalling_tests_utf8_dangling_out (gchar **utf8) @@ -1083,7 +1083,7 @@ g_i_marshalling_tests_utf8_dangling_out (gchar **utf8) /** * g_i_marshalling_tests_utf8_none_inout: - * utf8: (inout) (transfer none): + * @utf8: (inout) (transfer none): */ void g_i_marshalling_tests_utf8_none_inout (gchar **utf8) @@ -1094,7 +1094,7 @@ g_i_marshalling_tests_utf8_none_inout (gchar **utf8) /** * g_i_marshalling_tests_utf8_full_inout: - * utf8: (inout) (transfer full): + * @utf8: (inout) (transfer full): */ void g_i_marshalling_tests_utf8_full_inout (gchar **utf8) @@ -1617,7 +1617,8 @@ g_i_marshalling_tests_bytearray_none_in (GByteArray *array_) /** * g_i_marshalling_tests_gstrv_return: - * Returns: + * + * Returns: an array of strings */ GStrv g_i_marshalling_tests_gstrv_return (void) @@ -3384,8 +3385,8 @@ g_i_marshalling_tests_test_interface_test_int8_in (GIMarshallingTestsInterface * /** * g_i_marshalling_tests_int_out_out: - * int0: (out): - * int1: (out): + * @int0: (out): + * @int1: (out): */ void g_i_marshalling_tests_int_out_out (gint *int0, gint *int1) @@ -3396,7 +3397,7 @@ g_i_marshalling_tests_int_out_out (gint *int0, gint *int1) /** * g_i_marshalling_tests_int_return_out: - * int_: (out): + * @int_: (out): */ gint g_i_marshalling_tests_int_return_out (gint *int_) diff --git a/giscanner/annotationparser.py b/giscanner/annotationparser.py index 01cbb1ac..715ffe47 100644 --- a/giscanner/annotationparser.py +++ b/giscanner/annotationparser.py @@ -21,7 +21,6 @@ # AnnotationParser - parses gtk-doc annotations import re -import sys from .ast import (Array, Bitfield, Callback, Class, Enum, Field, Function, Interface, List, Map, Parameter, Property, Record, Return, @@ -49,7 +48,6 @@ TAG_VFUNC = 'virtual' TAG_SINCE = 'since' TAG_DEPRECATED = 'deprecated' TAG_RETURNS = 'returns' -TAG_RETURNS_ALT = 'return value' TAG_ATTRIBUTES = 'attributes' TAG_RENAME_TO = 'rename to' TAG_TYPE = 'type' @@ -100,14 +98,7 @@ class DocBlock(object): return '<DocBlock %r %r>' % (self.name, self.options) def get(self, name): - if name == TAG_RETURNS: - value = self.tags.get(name) - if value is None: - return self.tags.get(TAG_RETURNS_ALT) - else: - return value - else: - return self.tags.get(name) + return self.tags.get(name) class DocTag(object): @@ -152,6 +143,10 @@ class Option(object): class AnnotationParser(object): + WHITESPACE_RE = re.compile(r'^\s*$') + ASCII_TEXT_RE = re.compile(r'\s*[A-Za-z]+') + OPTION_RE = re.compile(r'\([A-Za-z]+[^(]*\)') + RETURNS_RE = re.compile(r'^return(s?)( value)?:', re.IGNORECASE) def __init__(self, namespace, source_scanner, transformer): self._blocks = {} @@ -195,64 +190,97 @@ class AnnotationParser(object): cpos = block_header.find(': ') if cpos: block_name = block_header[:cpos] - block_options, rest = self._parse_options(block_header[cpos+2:]) - if rest: - return + block_options = self.parse_options(block_header[cpos+2:]) else: block_name, block_options = block_header, {} block = DocBlock(block_name, block_options) + debug = block_name == 'annotation_object_compute_sum_n' comment_lines = [] - parse_parameters = True - canon_name = '' + parsing_parameters = True + last_param_tag = None + + # Second phase: parse parameters, return values, Tag: format + # annotations. + # + # Valid lines look like: + # * @foo: some comment here + # * @baz: (inout): This has an annotation + # * @bar: (out) (allow-none): this is a long parameter comment + # * that gets wrapped to the next line. + # * + # * Some documentation for the function. + # * + # * Returns: (transfer none): A value for line in comment[pos+1:].split('\n'): line = line.lstrip() - line = line[2:].strip() # Skip ' *' - if not line: - if parse_parameters: - parse_parameters = False + if (not line.startswith('*') or + self.WHITESPACE_RE.match(line[1:])): + # As soon as we find a line that's just whitespace, + # we're done parsing the parameters. + parsing_parameters = False continue - if line.startswith('@'): - line = line[1:] - elif not ': ' in line: - if parse_parameters and line: - if canon_name != '' and canon_name in block.tags: - block.tags[canon_name].comment += ' ' + line + + line = line[1:].lstrip() + + # Look for a parameter or return value. Both of these can + # have parenthesized options. + first_colonspace_index = line.find(': ') + is_parameter = line.startswith('@') + is_return_value = self.RETURNS_RE.search(line) + if ((is_parameter or is_return_value) + and first_colonspace_index > 0): + if is_parameter: + argname = line[1:first_colonspace_index] + else: + argname = TAG_RETURNS + tag = DocTag(argname) + second_colon_index = line.rfind(':') + found_options = False + if second_colon_index > first_colonspace_index: + value_line = \ + line[first_colonspace_index+2:second_colon_index] + if self.OPTION_RE.search(value_line): + # The OPTION_RE is a little bit heuristic. If + # we found two colons, we scan inside for something + # that looks like (foo). + # *Ideally* we'd change the gtk-doc format to + # require double colons, and then there'd be + # no ambiguity. I.e.: + # @foo:: Some documentation here + # But that'd be a rather incompatible change. + found_options = True + tag.comment = line[second_colon_index+1:].strip() + tag.options = self.parse_options(value_line) + if not found_options: + # We didn't find any options, so just take the whole thing + # as documentation. + tag.comment = line[first_colonspace_index+2:].strip() + block.tags[argname] = tag + last_param_tag = tag + elif (not is_parameter) and parsing_parameters and last_param_tag: + # We need to handle continuation lines on parameters. The + # conditional above - if a line doesn't start with '@', we're + # not yet in the documentation block for the whole function, + # and we've seen at least one parameter. + last_param_tag.comment += (' ' + line.strip()) + elif first_colonspace_index > 0: + # The line is of the form "Tag: some value here", like: + # Since: 0.8 + tag_name = line[:first_colonspace_index] + if self.ASCII_TEXT_RE.match(tag_name): + tag_name = tag_name.lower() + tag = DocTag(tag_name) + tag.value = line[first_colonspace_index+2:] + block.tags[tag_name] = tag else: comment_lines.append(line) - continue - tag_name, value = self._split_tag_namevalue(line) - canon_name = tag_name.lower() - if canon_name in block.tags: - print >> sys.stderr, ( - "Symbol %s has multiple definition of tag %r" % ( - block_name, canon_name, )) - block.tags[canon_name] = self._create_tag(canon_name, value) + elif (not is_parameter): + comment_lines.append(line) block.comment = '\n'.join(comment_lines) self._blocks[block.name] = block - def _split_tag_namevalue(self, raw): - """Split a line into tag name and value""" - parts = raw.split(': ', 1) - if len(parts) == 1: - tag_name = parts[0] - value = '' - if tag_name.endswith(':'): - tag_name = tag_name[:-1] - else: - tag_name, value = parts - return (tag_name, value) - - def _create_tag(self, tag_name, value): - # Tag: bar - # Tag: bar opt1 opt2 - tag = DocTag(tag_name) - tag.value = value - options, rest = self._parse_options(tag.value) - tag.options = options - tag.comment = rest or '' - return tag - - def _parse_options(self, value): + @classmethod + def parse_options(cls, value): # (foo) # (bar opt1 opt2...) opened = -1 @@ -277,11 +305,7 @@ class AnnotationParser(object): last = i + 2 opened = -1 - if last is not None: - rest = value[last:].strip() - else: - rest = None - return options, rest + return options class AnnotationApplier(object): @@ -871,7 +895,8 @@ class AnnotationApplier(object): annos_tag = self._get_tag(block, TAG_ATTRIBUTES) if annos_tag is None: return - for key, value in annos_tag.options.iteritems(): + options = AnnotationParser.parse_options(annos_tag.value) + for key, value in options.iteritems(): if value: node.attributes.append((key, value.one())) diff --git a/tests/scanner/annotation-1.0-expected.gir b/tests/scanner/annotation-1.0-expected.gir index 12025ed8..cf974f5e 100644 --- a/tests/scanner/annotation-1.0-expected.gir +++ b/tests/scanner/annotation-1.0-expected.gir @@ -83,14 +83,14 @@ and/or use gtk-doc annotations. --> glib:type-struct="ObjectClass"> <attribute name="org.example.Test" value="cows"/> <method name="method" c:identifier="annotation_object_method"> - <return-value transfer-ownership="none"> + <return-value transfer-ownership="none" doc="an int"> <type name="int" c:type="gint"/> </return-value> </method> <method name="out" c:identifier="annotation_object_out" doc="This is a test for out arguments"> - <return-value transfer-ownership="none"> + <return-value transfer-ownership="none" doc="an int"> <type name="int" c:type="gint"/> </return-value> <parameters> @@ -129,7 +129,7 @@ and/or use gtk-doc annotations. --> <method name="inout" c:identifier="annotation_object_inout" doc="This is a test for out arguments"> - <return-value transfer-ownership="none"> + <return-value transfer-ownership="none" doc="an int"> <type name="int" c:type="gint"/> </return-value> <parameters> @@ -145,7 +145,7 @@ and/or use gtk-doc annotations. --> <method name="inout2" c:identifier="annotation_object_inout2" doc="This is a second test for out arguments"> - <return-value transfer-ownership="none"> + <return-value transfer-ownership="none" doc="an int"> <type name="int" c:type="gint"/> </return-value> <parameters> @@ -161,7 +161,7 @@ and/or use gtk-doc annotations. --> <method name="inout3" c:identifier="annotation_object_inout3" doc="This is a 3th test for out arguments"> - <return-value transfer-ownership="none"> + <return-value transfer-ownership="none" doc="an int"> <type name="int" c:type="gint"/> </return-value> <parameters> @@ -178,7 +178,7 @@ and/or use gtk-doc annotations. --> <method name="in" c:identifier="annotation_object_in" doc="This is a test for in arguments"> - <return-value transfer-ownership="none"> + <return-value transfer-ownership="none" doc="an int"> <type name="int" c:type="gint"/> </return-value> <parameters> @@ -192,7 +192,7 @@ and/or use gtk-doc annotations. --> <method name="calleeowns" c:identifier="annotation_object_calleeowns" doc="This is a test for out arguments; GObject defaults to transfer"> - <return-value transfer-ownership="none"> + <return-value transfer-ownership="none" doc="an int"> <type name="int" c:type="gint"/> </return-value> <parameters> @@ -208,7 +208,7 @@ and/or use gtk-doc annotations. --> <method name="calleesowns" c:identifier="annotation_object_calleesowns" doc="This is a test for out arguments, one transferred, other not"> - <return-value transfer-ownership="none"> + <return-value transfer-ownership="none" doc="an int"> <type name="int" c:type="gint"/> </return-value> <parameters> @@ -312,7 +312,9 @@ intentionally similar example to gtk_container_get_children"> <type name="int"/> </array> </parameter> - <parameter name="n_nums" transfer-ownership="none"> + <parameter name="n_nums" + transfer-ownership="none" + doc="Length of number array"> <type name="int" c:type="int"/> </parameter> </parameters> @@ -331,7 +333,9 @@ intentionally similar example to gtk_container_get_children"> <type name="int"/> </array> </parameter> - <parameter name="n_nums" transfer-ownership="none"> + <parameter name="n_nums" + transfer-ownership="none" + doc="Length of number array"> <type name="int" c:type="int"/> </parameter> </parameters> @@ -364,7 +368,7 @@ intentionally similar example to gtk_container_get_children"> <method name="string_out" c:identifier="annotation_object_string_out" doc="Test returning a string as an out parameter"> - <return-value transfer-ownership="none"> + <return-value transfer-ownership="none" doc="some boolean"> <type name="boolean" c:type="gboolean"/> </return-value> <parameters> @@ -391,7 +395,9 @@ intentionally similar example to gtk_container_get_children"> doc="Callback to invoke"> <type name="ForeachFunc" c:type="AnnotationForeachFunc"/> </parameter> - <parameter name="user_data" transfer-ownership="none"> + <parameter name="user_data" + transfer-ownership="none" + doc="Callback user data"> <type name="any" c:type="gpointer"/> </parameter> </parameters> @@ -408,7 +414,9 @@ intentionally similar example to gtk_container_get_children"> <type name="uint8"/> </array> </parameter> - <parameter name="length" transfer-ownership="none"> + <parameter name="length" + transfer-ownership="none" + doc="Length of the data"> <type name="size_t" c:type="gsize"/> </parameter> </parameters> @@ -425,7 +433,9 @@ intentionally similar example to gtk_container_get_children"> <type name="int8"/> </array> </parameter> - <parameter name="length" transfer-ownership="none"> + <parameter name="length" + transfer-ownership="none" + doc="Length of the data"> <type name="size_t" c:type="gsize"/> </parameter> </parameters> @@ -443,7 +453,9 @@ type."> <type name="uint8"/> </array> </parameter> - <parameter name="length" transfer-ownership="none"> + <parameter name="length" + transfer-ownership="none" + doc="Length of the data"> <type name="size_t" c:type="gsize"/> </parameter> </parameters> @@ -467,13 +479,19 @@ type."> transfer-ownership="none" scope="notified" closure="2" - destroy="3"> + destroy="3" + doc="The callback"> <type name="ForeachFunc" c:type="AnnotationForeachFunc"/> </parameter> - <parameter name="user_data" transfer-ownership="none"> + <parameter name="user_data" + transfer-ownership="none" + doc="The callback data"> <type name="any" c:type="gpointer"/> </parameter> - <parameter name="destroy" transfer-ownership="none" scope="call"> + <parameter name="destroy" + transfer-ownership="none" + scope="call" + doc="Destroy notification"> <type name="GLib.DestroyNotify" c:type="GDestroyNotify"/> </parameter> </parameters> @@ -526,7 +544,7 @@ type."> <type name="none" c:type="void"/> </return-value> <parameters> - <parameter name="arg1" transfer-ownership="none"> + <parameter name="object" transfer-ownership="none"> <type name="any" c:type="gpointer"/> </parameter> </parameters> @@ -586,7 +604,9 @@ it says it's pointer but it's actually a string." <type name="int" c:type="gint"/> </return-value> <parameters> - <parameter name="object" transfer-ownership="none"> + <parameter name="object" + transfer-ownership="none" + doc="A #AnnotationObject."> <type name="Object" c:type="AnnotationObject*"/> </parameter> <parameter name="data" transfer-ownership="none" doc="Some data."> @@ -648,6 +668,19 @@ detection, and fixing it via annotations."> </parameter> </parameters> </function> + <function name="invalid_annotation" + c:identifier="annotation_invalid_annotation"> + <return-value transfer-ownership="none"> + <type name="none" c:type="void"/> + </return-value> + <parameters> + <parameter name="foo" + transfer-ownership="none" + doc="some text (e.g. example) or else"> + <type name="int" c:type="int"/> + </parameter> + </parameters> + </function> <function name="ptr_array" c:identifier="annotation_ptr_array"> <return-value transfer-ownership="none"> <type name="none" c:type="void"/> diff --git a/tests/scanner/annotation-1.0-expected.tgir b/tests/scanner/annotation-1.0-expected.tgir index 0f8a5fe7..d8dfc381 100644 --- a/tests/scanner/annotation-1.0-expected.tgir +++ b/tests/scanner/annotation-1.0-expected.tgir @@ -383,7 +383,7 @@ <type name="none"/> </return-value> <parameters> - <parameter name="arg1" transfer-ownership="none"> + <parameter name="object" transfer-ownership="none"> <type name="any"/> </parameter> </parameters> @@ -476,6 +476,16 @@ </parameter> </parameters> </function> + <function name="invalid_annotation" c:identifier="annotation_invalid_annotation"> + <return-value transfer-ownership="none"> + <type name="none"/> + </return-value> + <parameters> + <parameter name="foo" transfer-ownership="none"> + <type name="int"/> + </parameter> + </parameters> + </function> <function name="ptr_array" c:identifier="annotation_ptr_array"> <return-value transfer-ownership="none"> <type name="none"/> diff --git a/tests/scanner/annotation.c b/tests/scanner/annotation.c index 64f9cc32..497d1eec 100644 --- a/tests/scanner/annotation.c +++ b/tests/scanner/annotation.c @@ -641,7 +641,7 @@ annotation_string_zero_terminated (void) /** * annotation_string_zero_terminated_out: - * @out: (array zero-terminated=1) (inout) + * @out: (array zero-terminated=1) (inout): **/ void annotation_string_zero_terminated_out (char ***out) @@ -737,4 +737,15 @@ annotation_attribute_func (AnnotationObject *object, return 42; } +/** + * annotation_invalid_annotation: + * @foo: some text (e.g. example) or else + */ +void +annotation_invalid_annotation (int foo) +{ + +} + + char backslash_parsing_tester_2 = '\\'; diff --git a/tests/scanner/annotation.h b/tests/scanner/annotation.h index ace36515..e4f29065 100644 --- a/tests/scanner/annotation.h +++ b/tests/scanner/annotation.h @@ -142,6 +142,8 @@ void annotation_set_source_file (const char *fname); gint annotation_attribute_func (AnnotationObject *object, const gchar *data); +void annotation_invalid_annotation (int foo); + /** * AnnotationStruct: * diff --git a/tests/scanner/foo-1.0-expected.gir b/tests/scanner/foo-1.0-expected.gir index 68896c11..f7ca794b 100644 --- a/tests/scanner/foo-1.0-expected.gir +++ b/tests/scanner/foo-1.0-expected.gir @@ -334,10 +334,10 @@ uses a C sugar return type."> <type name="none" c:type="void"/> </return-value> <parameters> - <parameter name="offset" transfer-ownership="none"> + <parameter name="offset" transfer-ownership="none" doc="offset"> <type name="int" c:type="int"/> </parameter> - <parameter name="length" transfer-ownership="none"> + <parameter name="length" transfer-ownership="none" doc="length"> <type name="int" c:type="int"/> </parameter> </parameters> @@ -443,10 +443,10 @@ uses a C sugar return type."> <type name="none" c:type="void"/> </return-value> <parameters> - <parameter name="offset" transfer-ownership="none"> + <parameter name="offset" transfer-ownership="none" doc="offset"> <type name="int" c:type="int"/> </parameter> - <parameter name="length" transfer-ownership="none"> + <parameter name="length" transfer-ownership="none" doc="length"> <type name="int" c:type="int"/> </parameter> </parameters> @@ -515,10 +515,10 @@ uses a C sugar return type."> <parameter name="object" transfer-ownership="none"> <type name="Object" c:type="FooObject*"/> </parameter> - <parameter name="offset" transfer-ownership="none"> + <parameter name="offset" transfer-ownership="none" doc="offset"> <type name="int" c:type="int"/> </parameter> - <parameter name="length" transfer-ownership="none"> + <parameter name="length" transfer-ownership="none" doc="length"> <type name="int" c:type="int"/> </parameter> </parameters> @@ -570,7 +570,9 @@ uses a C sugar return type."> <type name="none" c:type="void"/> </return-value> <parameters> - <parameter name="r2" transfer-ownership="none"> + <parameter name="r2" + transfer-ownership="none" + doc="source rectangle"> <type name="Rectangle" c:type="FooRectangle*"/> </parameter> </parameters> @@ -826,7 +828,7 @@ exposed to language bindings." <type name="none" c:type="void"/> </return-value> <parameters> - <parameter name="fs" transfer-ownership="none"> + <parameter name="fs" transfer-ownership="none" doc="a #FooSkippable"> <type name="Skippable" c:type="FooSkippable"/> </parameter> </parameters> |