diff options
9 files changed, 47 insertions, 10 deletions
diff --git a/giscanner/mallardwriter.py b/giscanner/mallardwriter.py index 8c228ce8..09701817 100644 --- a/giscanner/mallardwriter.py +++ b/giscanner/mallardwriter.py @@ -150,6 +150,7 @@ class DocstringScanner(TemplatedScanner): ('signal', r'#<<type_name:alpha>>::(<<signal_name:alpha_dash>>)'), ('type_name', r'#(<<type_name:alpha>>)'), ('fundamental', r'%(<<fundamental:alpha>>)'), + ('parameter', r'@<<param_name:alpha>>'), ('function_call', r'<<symbol_name:alpha>>\(\)'), ] @@ -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 '<code>%s</code>' % (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 5f27f96f..0312ab98 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 <link xref="DocExamples.Obj.new">doc_examples_obj_new</link>.</p><p </tr> <tr> <td><p>pointer_arg :</p></td> -<td><p>If not NULL, do a thing.</p></td> +<td><p>If not NULL, do a thing. Pass <code>first_arg</code> if you want to sometimes. You can also pass <code>second_arg</code>, or even <code>boolean_arg</code>.</p></td> </tr> <tr> <td><p>string :</p></td> 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 ae7791e9..f5f2145b 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.</p> </tr> <tr> <td><p>Returns :</p></td> -<td><p>TRUE if @out_arg is valid, FALSE otherwise</p></td> +<td><p>TRUE if <code>out_arg</code> is valid, FALSE otherwise</p></td> </tr> </table> </page> 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 98958b22..436d825f 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, </code></synopsis> <p>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)</p> +<code>user_data</code> parameter, while JS doesn't)</p> <table> <tr> @@ -48,7 +48,7 @@ will expose this in different ways (e.g. Python keeps the </tr> <tr> <td><p>destroy_notify :</p></td> -<td><p>how to get rid of @user_data</p></td> +<td><p>how to get rid of <code>user_data</code></p></td> </tr> <tr> <td><p>Returns :</p></td> 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 d83d2d82..0304b135 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 @@ </info> <title>DocExamples.Obj::signal-example</title> <synopsis><code mime="text/x-python"> -def callback(obj, int_param, float_param, user_param1, ...) +def callback(obj, int_param, float_param, pointer_param, user_param1, ...) </code></synopsis> <p>This is an example of how to document a signal.</p> @@ -28,6 +28,10 @@ def callback(obj, int_param, float_param, user_param1, ...) <td><p>a parameter of type float</p></td> </tr> <tr> +<td><p>pointer_param :</p></td> +<td><p>A pointer to @obj's thingy -- pass <code>int_param</code> if you really want to.</p></td> +</tr> +<tr> <td><p>user_param1 :</p></td> <td><p>first user parameter (if any) specified with the connect() method</p></td> </tr> 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 02f3a002..603fb46c 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 <link xref="DocExamples.Obj.new">Obj.new</link>.</p><p>This should </tr> <tr> <td><p>pointer_arg :</p></td> -<td><p>If not None, do a thing.</p></td> +<td><p>If not None, do a thing. Pass <code>self</code> if you want to sometimes. You can also pass <code>second_arg</code>, or even <code>boolean_arg</code>.</p></td> </tr> <tr> <td><p>string :</p></td> 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 d7990e03..8897c785 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.</p> </tr> <tr> <td><p>Returns :</p></td> -<td><p>True if @out_arg is valid, False otherwise</p></td> +<td><p>True if <code>out_arg</code> is valid, False otherwise</p></td> </tr> </table> </page> 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 ace76458..0b6a15cb 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) </code></synopsis> <p>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)</p> +<code>user_data</code> parameter, while JS doesn't)</p> <table> <tr> @@ -48,7 +48,7 @@ will expose this in different ways (e.g. Python keeps the </tr> <tr> <td><p>destroy_notify :</p></td> -<td><p>how to get rid of @user_data</p></td> +<td><p>how to get rid of <code>user_data</code></p></td> </tr> </table> </page> diff --git a/tests/doctool/doc-examples-obj.c b/tests/doctool/doc-examples-obj.c index 992e7151..bf4fcc7e 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. |