From: Jasper St. Pierre Date: Wed, 9 Jan 2013 07:31:22 +0000 (-0500) Subject: mallardwriter: Add support for parameters X-Git-Tag: GOBJECT_INTROSPECTION_1_35_4~17 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=c357dd59730b266f4ccc095e628b69520aff5977;p=platform%2Fupstream%2Fgobject-introspection.git mallardwriter: Add support for parameters Support the inline @my_parameter syntax, and translate it to my_parameter, as Mallard doesn't have anything more fancy than that. For Python, where we omit the first parameter of methods like that automatically, force to "self". --- diff --git a/giscanner/mallardwriter.py b/giscanner/mallardwriter.py index 8c228ce..0970181 100644 --- a/giscanner/mallardwriter.py +++ b/giscanner/mallardwriter.py @@ -150,6 +150,7 @@ class DocstringScanner(TemplatedScanner): ('signal', r'#<>::(<>)'), ('type_name', r'#(<>)'), ('fundamental', r'%(<>)'), + ('parameter', r'@<>'), ('function_call', r'<>\(\)'), ] @@ -239,6 +240,14 @@ class MallardFormatter(object): def _process_fundamental(self, node, match, props): return self.fundamentals.get(props['fundamental'], match) + def _process_parameter(self, node, match, props): + try: + parameter = node.get_parameter(props['param_name']) + except (AttributeError, ValueError), e: + return match + + return '%s' % (self.format_parameter_name(node, parameter), ) + def _process_function_call(self, node, match, props): func = self._resolve_symbol(props['symbol_name']) if func is None: @@ -255,6 +264,7 @@ class MallardFormatter(object): 'signal': self._process_signal, 'type_name': self._process_type_name, 'fundamental': self._process_fundamental, + 'parameter': self._process_parameter, 'function_call': self._process_function_call, } @@ -265,6 +275,9 @@ class MallardFormatter(object): words = [self._process_token(node, tok) for tok in tokens] return ''.join(words) + def format_parameter_name(self, node, parameter): + return parameter.argname + def format_function_name(self, func): raise NotImplementedError @@ -344,6 +357,22 @@ class MallardFormatterPython(MallardFormatter): "NULL": "None", } + def is_method(self, node): + if getattr(node, "is_method", False): + return True + + if isinstance(node, (ast.VFunction)): + return True + + return False + + def format_parameter_name(self, node, parameter): + # Force "self" for the first parameter of a method + if self.is_method(node) and parameter is node.parameters[0]: + return "self" + else: + return parameter.argname + def format_type(self, type_): if isinstance(type_, ast.Array): return '[' + self.format_type(type_.element_type) + ']' diff --git a/tests/doctool/DocExamples-1.0-C-expected/DocExamples.Obj.method.page b/tests/doctool/DocExamples-1.0-C-expected/DocExamples.Obj.method.page index 5f27f96..0312ab9 100644 --- a/tests/doctool/DocExamples-1.0-C-expected/DocExamples.Obj.method.page +++ b/tests/doctool/DocExamples-1.0-C-expected/DocExamples.Obj.method.page @@ -66,7 +66,7 @@ created with doc_examples_obj_new.

pointer_arg :

-

If not NULL, do a thing.

+

If not NULL, do a thing. Pass first_arg if you want to sometimes. You can also pass second_arg, or even boolean_arg.

string :

diff --git a/tests/doctool/DocExamples-1.0-C-expected/DocExamples.Obj.static_method.page b/tests/doctool/DocExamples-1.0-C-expected/DocExamples.Obj.static_method.page index ae7791e..f5f2145 100644 --- a/tests/doctool/DocExamples-1.0-C-expected/DocExamples.Obj.static_method.page +++ b/tests/doctool/DocExamples-1.0-C-expected/DocExamples.Obj.static_method.page @@ -33,7 +33,7 @@ and a return value.

Returns :

-

TRUE if @out_arg is valid, FALSE otherwise

+

TRUE if out_arg is valid, FALSE otherwise

diff --git a/tests/doctool/DocExamples-1.0-C-expected/DocExamples.callback_function.page b/tests/doctool/DocExamples-1.0-C-expected/DocExamples.callback_function.page index 98958b2..436d825 100644 --- a/tests/doctool/DocExamples-1.0-C-expected/DocExamples.callback_function.page +++ b/tests/doctool/DocExamples-1.0-C-expected/DocExamples.callback_function.page @@ -35,7 +35,7 @@ void doc_examples_callback_function (DocExamplesCallback callback,

This is a function that takes a callback. Different languages will expose this in different ways (e.g. Python keeps the -@user_data parameter, while JS doesn't)

+user_data parameter, while JS doesn't)

@@ -48,7 +48,7 @@ will expose this in different ways (e.g. Python keeps the - + diff --git a/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.Obj-signal-example.page b/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.Obj-signal-example.page index d83d2d8..0304b13 100644 --- a/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.Obj-signal-example.page +++ b/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.Obj-signal-example.page @@ -10,7 +10,7 @@ DocExamples.Obj::signal-example -def callback(obj, int_param, float_param, user_param1, ...) +def callback(obj, int_param, float_param, pointer_param, user_param1, ...)

This is an example of how to document a signal.

@@ -28,6 +28,10 @@ def callback(obj, int_param, float_param, user_param1, ...) + + + + diff --git a/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.Obj.method.page b/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.Obj.method.page index 02f3a00..603fb46 100644 --- a/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.Obj.method.page +++ b/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.Obj.method.page @@ -63,7 +63,7 @@ created with Obj.new.

This should

- + diff --git a/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.Obj.static_method.page b/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.Obj.static_method.page index d7990e0..8897c78 100644 --- a/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.Obj.static_method.page +++ b/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.Obj.static_method.page @@ -35,7 +35,7 @@ and a return value.

- +

destroy_notify :

how to get rid of @user_data

how to get rid of user_data

Returns :

a parameter of type float

pointer_param :

A pointer to @obj's thingy -- pass int_param if you really want to.

user_param1 :

first user parameter (if any) specified with the connect() method

pointer_arg :

If not None, do a thing.

If not None, do a thing. Pass self if you want to sometimes. You can also pass second_arg, or even boolean_arg.

string :

Returns :

True if @out_arg is valid, False otherwise

True if out_arg is valid, False otherwise
diff --git a/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.callback_function.page b/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.callback_function.page index ace7645..0b6a15c 100644 --- a/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.callback_function.page +++ b/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.callback_function.page @@ -35,7 +35,7 @@ def callback_function(callback, user_data, destroy_notify)

This is a function that takes a callback. Different languages will expose this in different ways (e.g. Python keeps the -@user_data parameter, while JS doesn't)

+user_data parameter, while JS doesn't)

@@ -48,7 +48,7 @@ will expose this in different ways (e.g. Python keeps the - +

destroy_notify :

how to get rid of @user_data

how to get rid of user_data
diff --git a/tests/doctool/doc-examples-obj.c b/tests/doctool/doc-examples-obj.c index 992e715..bf4fcc7 100644 --- a/tests/doctool/doc-examples-obj.c +++ b/tests/doctool/doc-examples-obj.c @@ -56,6 +56,8 @@ doc_examples_obj_class_init (DocExamplesObjClass *klass) * @obj: * @int_param: a parameter of type int * @float_param: a parameter of type float + * @pointer_param: A pointer to @obj's thingy -- + * pass @int_param if you really want to. * * This is an example of how to document a signal. * @@ -66,7 +68,7 @@ doc_examples_obj_class_init (DocExamplesObjClass *klass) G_SIGNAL_RUN_LAST, 0, NULL, NULL, NULL, - G_TYPE_NONE, 2, G_TYPE_UINT, G_TYPE_UINT); + G_TYPE_NONE, 3, G_TYPE_UINT, G_TYPE_UINT, G_TYPE_POINTER); /** * DocExamplesObj:property-example: @@ -106,6 +108,8 @@ doc_examples_obj_new (void) * @second_arg: second argument * @boolean_arg: You should always pass %TRUE. * @pointer_arg: (allow-none): If not %NULL, do a thing. + * Pass @first_arg if you want to sometimes. You can + * also pass @second_arg, or even @boolean_arg. * @string: A %NULL-terminated string. * * This is an example of how to document a method.