From c357dd59730b266f4ccc095e628b69520aff5977 Mon Sep 17 00:00:00 2001
From: "Jasper St. Pierre" 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".
---
giscanner/mallardwriter.py | 29 ++++++++++++++++++++++
.../DocExamples.Obj.method.page | 2 +-
.../DocExamples.Obj.static_method.page | 2 +-
.../DocExamples.callback_function.page | 4 +--
.../DocExamples.Obj-signal-example.page | 6 ++++-
.../DocExamples.Obj.method.page | 2 +-
.../DocExamples.Obj.static_method.page | 2 +-
.../DocExamples.callback_function.page | 4 +--
tests/doctool/doc-examples-obj.c | 6 ++++-
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'#<%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 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 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 :
Returns :
TRUE if @out_arg is valid, FALSE otherwise
TRUE if out_arg
is valid, FALSE otherwise
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)
destroy_notify : |
-how to get rid of @user_data |
+how to get rid of |
Returns : |
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 @@
a parameter of type float |
|
pointer_param : |
+A pointer to @obj's thingy -- pass |
+|
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 |
string : |
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.
||
Returns : |
-True if @out_arg is valid, False otherwise |
+True if |
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)
destroy_notify : |
-how to get rid of @user_data |
+how to get rid of |