[gobject-introspection/wip/docs: 3/23] mallardwriter: Parse %ENUM_FIELDs

[Jasper St. Pierre <jstpierre src gnome org>]

commit edec66f3826b160065db575c3dc9c81031dfb075
Author: Jasper St. Pierre <jstpierre mecheye net>
Date:   Wed Jan 30 10:07:59 2013 -0500

    mallardwriter: Parse %ENUM_FIELDs

 giscanner/mallardwriter.py                         |   25 ++++++++++++++-----
 .../DocExamples.callback_function.page             |   10 ++++----
 .../DocExamples.callback_function.page             |    8 ++++-
 tests/doctool/doc-examples-obj.c                   |    7 ++++-
 tests/doctool/doc-examples-obj.h                   |    6 ++--
 5 files changed, 38 insertions(+), 18 deletions(-)
---
diff --git a/giscanner/mallardwriter.py b/giscanner/mallardwriter.py
index 74bb3d6..b7385fe 100644
--- a/giscanner/mallardwriter.py
+++ b/giscanner/mallardwriter.py
@@ -150,7 +150,7 @@ class DocstringScanner(TemplatedScanner):
             ('property', r'#<<type_name:alpha>>:(<<property_name:alpha_dash>>)'),
             ('signal', r'#<<type_name:alpha>>::(<<signal_name:alpha_dash>>)'),
             ('type_name', r'#(<<type_name:alpha>>)'),
-            ('fundamental', r'%(<<fundamental:alpha>>)'),
+            ('enum_value', r'%(<<member_name:alpha>>)'),
             ('parameter', r'@<<param_name:alpha>>'),
             ('function_call', r'<<symbol_name:alpha>>\(\)'),
         ]
@@ -238,12 +238,19 @@ class MallardFormatter(object):
 
         return self.format_xref(type_)
 
-    def _process_fundamental(self, node, match, props):
-        fundamental = props['fundamental']
+    def _process_enum_value(self, node, match, props):
+        member_name = props['member_name']
+
         try:
-            return '<code>%s</code>' % (self.fundamentals[fundamental],)
+            return '<code>%s</code>' % (self.fundamentals[member_name], )
         except KeyError:
-            return match
+            pass
+
+        enum_value = self._resolve_symbol(member_name)
+        if enum_value:
+            return self.format_xref(enum_value)
+
+        return match
 
     def _process_parameter(self, node, match, props):
         try:
@@ -268,7 +275,7 @@ class MallardFormatter(object):
             'property': self._process_property,
             'signal': self._process_signal,
             'type_name': self._process_type_name,
-            'fundamental': self._process_fundamental,
+            'enum_value': self._process_enum_value,
             'parameter': self._process_parameter,
             'function_call': self._process_function_call,
         }
@@ -305,7 +312,11 @@ class MallardFormatter(object):
             return make_page_id(node)
 
     def format_xref(self, node):
-        return '<link xref="%s">%s</link>' % (make_page_id(node), self.format_page_name(node))
+        if isinstance(node, ast.Member):
+            # Enum/BitField members are linked to the main enum page.
+            return self.format_xref(node.parent) + '.' + node.name
+        else:
+            return '<link xref="%s">%s</link>' % (make_page_id(node), self.format_page_name(node))
 
     def format_property_flags(self, property_, construct_only=False):
         flags = []
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 436d825..19d10b2 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
@@ -10,7 +10,7 @@
     <link type="guide" xref="index" group="function"/>
     <api:function>
       <api:returns>
-        <api:type>void</api:type>
+        <api:type>DocExamplesEnum</api:type>
       </api:returns>
       <api:name>doc_examples_callback_function</api:name>
       <api:arg>
@@ -29,9 +29,9 @@
   </info>
   <title>doc_examples_callback_function</title>
 <synopsis><code mime="text/x-csrc">
-void doc_examples_callback_function (DocExamplesCallback callback,
-                                     gpointer user_data,
-                                     GDestroyNotify destroy_notify);
+DocExamplesEnum doc_examples_callback_function (DocExamplesCallback callback,
+                                                gpointer user_data,
+                                                GDestroyNotify 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
@@ -52,7 +52,7 @@ will expose this in different ways (e.g. Python keeps the
 </tr>
 <tr>
 <td><p>Returns :</p></td>
-<td></td>
+<td><p><link xref="DocExamples.Enum">DocExamples.Enum</link>.foo sometimes, <link xref="DocExamples.Enum">DocExamples.Enum</link>.bar other times.</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 f1b4905..a834cfb 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
@@ -10,7 +10,7 @@
     <link type="guide" xref="index" group="function"/>
     <api:function>
       <api:returns>
-        <api:type>none</api:type>
+        <api:type>DocExamples.Enum</api:type>
       </api:returns>
       <api:name>doc_examples_callback_function</api:name>
       <api:arg>
@@ -30,7 +30,7 @@
   <title>callback_function</title>
 <synopsis><code mime="text/x-python">
 @accepts(DocExamples.Callback, gpointer, GLib.DestroyNotify)
- returns(none)
+ returns(DocExamples.Enum)
 def callback_function(callback, user_data, destroy_notify):
     # Python wrapper for doc_examples_callback_function()
 </code></synopsis>
@@ -51,5 +51,9 @@ will expose this in different ways (e.g. Python keeps the
 <td><p>destroy_notify :</p></td>
 <td><p>how to get rid of <code>user_data</code></p></td>
 </tr>
+<tr>
+<td><p>Returns :</p></td>
+<td><p><link xref="DocExamples.Enum">DocExamples.Enum</link>.foo sometimes, <link xref="DocExamples.Enum">DocExamples.Enum</link>.bar other times.</p></td>
+</tr>
 </table>
 </page>
diff --git a/tests/doctool/doc-examples-obj.c b/tests/doctool/doc-examples-obj.c
index 60150f8..08341c8 100644
--- a/tests/doctool/doc-examples-obj.c
+++ b/tests/doctool/doc-examples-obj.c
@@ -180,8 +180,11 @@ doc_examples_array_function (gint *out_len)
  * 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)
+ *
+ * Returns: %DOC_EXAMPLES_FOO sometimes, %DOC_EXAMPLES_BAR
+ *   other times.
  */
-void
+DocExamplesEnum
 doc_examples_callback_function (DocExamplesCallback callback,
                                 gpointer            user_data,
                                 GDestroyNotify      destroy_notify)
@@ -193,4 +196,6 @@ doc_examples_callback_function (DocExamplesCallback callback,
 
   if (user_data && destroy_notify)
     destroy_notify (user_data);
+
+  return DOC_EXAMPLES_FOO;
 }
diff --git a/tests/doctool/doc-examples-obj.h b/tests/doctool/doc-examples-obj.h
index e7aba55..641aa81 100644
--- a/tests/doctool/doc-examples-obj.h
+++ b/tests/doctool/doc-examples-obj.h
@@ -84,9 +84,9 @@ typedef enum {
  */
 typedef gchar * (*DocExamplesCallback) (int one, int two);
 
-void doc_examples_callback_function (DocExamplesCallback callback,
-                                     gpointer            user_data,
-                                     GDestroyNotify      destroy_notify);
+DocExamplesEnum doc_examples_callback_function (DocExamplesCallback callback,
+                                                gpointer            user_data,
+                                                GDestroyNotify      destroy_notify);
 
 G_END_DECLS