[gobject-introspection] giscanner: fix description field storage in .gir files

[Colin Walters <walters src gnome org>]

commit 556bb8ee3402b92e2936ed3b594cdfc0b04a9db5
Author: Dieter Verfaillie <dieterv optionexplicit be>
Date:   Tue May 21 10:47:11 2013 +0200

    giscanner: fix description field storage in .gir files
    
    GTK-Doc description fields for tags can contain multiple lines and
    even multiple paragraphs. Whitespace cannot be preserved in XML
    attributes, so we move the "deprecated" description text into
    a "<doc-deprecated />" element right next to where we already have
    the "<doc />" element. Keep the "deprecated" attribute around for
    backwards compatibility though, but set its value to "1" (analogous
    to the "writable", "contruct", etc attributes) if the annotated
    symbol is marked as deprecated.
    
    While at it, add <doc-version /> and <doc-stability /> which
    was not yet available in the .gir files...
    
    This takes care of the "Since:", "Stability:" and "Deprecated:"
    GTK-Doc tags. Nothing needs to be done for the "Returns:" tag as
    as we already write a "<doc />" child element on "<return-value />".

 girepository/girparser.c               |    3 ++-
 giscanner/ast.py                       |    4 +++-
 giscanner/girparser.py                 |   20 ++++++++++++++++----
 giscanner/girwriter.py                 |   27 +++++++++++++++++++++++----
 giscanner/maintransformer.py           |    8 ++++++--
 tests/scanner/Regress-1.0-expected.gir |   14 ++++++++++----
 tests/scanner/regress.c                |    9 ++++++---
 7 files changed, 66 insertions(+), 19 deletions(-)
---
diff --git a/girepository/girparser.c b/girepository/girparser.c
index 6fbf2a6..82005fc 100644
--- a/girepository/girparser.c
+++ b/girepository/girparser.c
@@ -2748,7 +2748,8 @@ start_element_handler (GMarkupParseContext *context,
                               attribute_names, attribute_values,
                               ctx, error))
        goto out;
-      if (strcmp (element_name, "doc") == 0)
+      if (strcmp ("doc", element_name) == 0 || strcmp ("doc-deprecated", element_name) == 0 ||
+          strcmp ("doc-stability", element_name) == 0 || strcmp ("doc-version", element_name) == 0)
         {
           state_switch (ctx, STATE_PASSTHROUGH);
           goto out;
diff --git a/giscanner/ast.py b/giscanner/ast.py
index 4c54b54..becc126 100644
--- a/giscanner/ast.py
+++ b/giscanner/ast.py
@@ -513,12 +513,14 @@ class Annotated(object):
 properties."""
     def __init__(self):
         self.version = None
+        self.version_doc = None
         self.skip = False
         self.introspectable = True
         self.attributes = []    # (key, value)*
         self.stability = None
+        self.stability_doc = None
         self.deprecated = None
-        self.deprecated_version = None
+        self.deprecated_doc = None
         self.doc = None
 
 
diff --git a/giscanner/girparser.py b/giscanner/girparser.py
index 35d985b..d01e753 100644
--- a/giscanner/girparser.py
+++ b/giscanner/girparser.py
@@ -177,12 +177,24 @@ class GIRParser(object):
         version = node.attrib.get('version')
         if version:
             obj.version = version
-        deprecated = node.attrib.get('deprecated')
+        version_doc = node.find(_corens('doc-version'))
+        if version_doc is not None:
+            if version_doc.text:
+                obj.version_doc = version_doc.text
+        deprecated = node.attrib.get('deprecated-version')
         if deprecated:
             obj.deprecated = deprecated
-        deprecated_version = node.attrib.get('deprecated-version')
-        if deprecated_version:
-            obj.deprecated_version = deprecated_version
+        deprecated_doc = node.find(_corens('doc-deprecated'))
+        if deprecated_doc is not None:
+            if deprecated_doc.text:
+                obj.deprecated_doc = deprecated_doc.text
+        stability = node.attrib.get('stability')
+        if stability:
+            obj.stability = stability
+        stability_doc = node.find(_corens('doc-stability'))
+        if stability_doc is not None:
+            if stability_doc.text:
+                obj.stability_doc = stability_doc.text
 
     def _parse_object_interface(self, node):
         parent = node.attrib.get('parent')
diff --git a/giscanner/girwriter.py b/giscanner/girwriter.py
index e7af253..e5841ec 100644
--- a/giscanner/girwriter.py
+++ b/giscanner/girwriter.py
@@ -125,18 +125,37 @@ class GIRWriter(XMLWriter):
     def _write_generic(self, node):
         for key, value in node.attributes:
             self.write_tag('attribute', [('name', key), ('value', value)])
+
         if hasattr(node, 'doc') and node.doc:
             self.write_tag('doc', [('xml:space', 'preserve')],
                            node.doc)
 
+        if hasattr(node, 'version_doc') and node.version_doc:
+            self.write_tag('doc-version', [('xml:space', 'preserve')],
+                           node.version_doc)
+
+        if hasattr(node, 'deprecated_doc') and node.deprecated_doc:
+            self.write_tag('doc-deprecated', [('xml:space', 'preserve')],
+                           node.deprecated_doc)
+
+        if hasattr(node, 'stability_doc') and node.stability_doc:
+            self.write_tag('doc-stability', [('xml:space', 'preserve')],
+                           node.stability_doc)
+
     def _append_node_generic(self, node, attrs):
         if node.skip or not node.introspectable:
             attrs.append(('introspectable', '0'))
+
+        if node.deprecated or node.deprecated_doc:
+            # The deprecated attribute used to contain node.deprecated_doc as an attribute. As
+            # an xml attribute cannot preserve whitespace, deprecated_doc has been moved into
+            # it's own tag, written in _write_generic() above. We continue to write the deprecated
+            # attribute for backwards compatibility
+            attrs.append(('deprecated', '1'))
+
         if node.deprecated:
-            attrs.append(('deprecated', node.deprecated))
-            if node.deprecated_version:
-                attrs.append(('deprecated-version',
-                              node.deprecated_version))
+            attrs.append(('deprecated-version', node.deprecated))
+
         if node.stability:
             attrs.append(('stability', node.stability))
 
diff --git a/giscanner/maintransformer.py b/giscanner/maintransformer.py
index ebb2b88..d356aac 100644
--- a/giscanner/maintransformer.py
+++ b/giscanner/maintransformer.py
@@ -588,18 +588,22 @@ class MainTransformer(object):
         if since_tag is not None:
             if since_tag.value:
                 node.version = since_tag.value
+            if since_tag.description:
+                node.version_doc = since_tag.description
 
         deprecated_tag = block.tags.get(TAG_DEPRECATED)
         if deprecated_tag is not None:
             if deprecated_tag.value:
-                node.deprecated_version = deprecated_tag.value
+                node.deprecated = deprecated_tag.value
             if deprecated_tag.description:
-                node.deprecated = deprecated_tag.description
+                node.deprecated_doc = deprecated_tag.description
 
         stability_tag = block.tags.get(TAG_STABILITY)
         if stability_tag is not None:
             if stability_tag.value:
                 node.stability = stability_tag.value
+            if stability_tag.description:
+                node.stability_doc = stability_tag.description
 
         attributes_annotation = block.annotations.get(ANN_ATTRIBUTES)
         if attributes_annotation is not None:
diff --git a/tests/scanner/Regress-1.0-expected.gir b/tests/scanner/Regress-1.0-expected.gir
index 0dadc59..94962c9 100644
--- a/tests/scanner/Regress-1.0-expected.gir
+++ b/tests/scanner/Regress-1.0-expected.gir
@@ -290,8 +290,9 @@ and/or use gtk-doc annotations.  -->
       </method>
       <method name="do_not_use"
               c:identifier="regress_annotation_object_do_not_use"
-              deprecated="Use regress_annotation_object_create_object() instead."
+              deprecated="1"
               deprecated-version="0.12">
+        <doc-deprecated xml:space="preserve">Use regress_annotation_object_create_object() 
instead.</doc-deprecated>
         <return-value transfer-ownership="none">
           <doc xml:space="preserve">%NULL always</doc>
           <type name="GObject.Object" c:type="GObject*"/>
@@ -740,12 +741,13 @@ regress_annotation_object_watch_full().</doc>
       </property>
       <property name="string-property"
                 version="1.0"
-                deprecated="Use better-string-property instead"
+                deprecated="1"
                 deprecated-version="1.2"
                 writable="1"
                 construct="1"
                 transfer-ownership="none">
         <doc xml:space="preserve">This is a property which is a string</doc>
+        <doc-deprecated xml:space="preserve">Use better-string-property instead</doc-deprecated>
         <type name="utf8" c:type="gchar*"/>
       </property>
       <property name="tab-property"
@@ -809,10 +811,11 @@ known by GObject as it's only marked as G_TYPE_POINTER</doc>
       <glib:signal name="string-signal"
                    when="last"
                    version="1.0"
-                   deprecated="Use other-signal instead"
+                   deprecated="1"
                    deprecated-version="1.2">
         <doc xml:space="preserve">This is a signal which has a broken signal handler,
 it says it's pointer but it's actually a string.</doc>
+        <doc-deprecated xml:space="preserve">Use other-signal instead</doc-deprecated>
         <return-value transfer-ownership="none">
           <type name="none" c:type="void"/>
         </return-value>
@@ -6414,9 +6417,12 @@ https://bugzilla.gnome.org/show_bug.cgi?id=685399</doc>
     <function name="test_versioning"
               c:identifier="regress_test_versioning"
               version="1.32.1"
-              deprecated="Use foobar instead"
+              deprecated="1"
               deprecated-version="1.33.3"
               stability="Unstable">
+      <doc-version xml:space="preserve">Actually, this function was introduced earlier than this, but it 
didn't do anything before this version.</doc-version>
+      <doc-deprecated xml:space="preserve">This function has been deprecated, because it sucks. Use foobar 
instead.</doc-deprecated>
+      <doc-stability xml:space="preserve">Maybe someday we will find the time to stabilize this function. 
Who knows?</doc-stability>
       <return-value transfer-ownership="none">
         <type name="none" c:type="void"/>
       </return-value>
diff --git a/tests/scanner/regress.c b/tests/scanner/regress.c
index aa9f83a..14df474 100644
--- a/tests/scanner/regress.c
+++ b/tests/scanner/regress.c
@@ -3980,9 +3980,12 @@ regress_has_parameter_named_attrs (int        foo,
 /**
  * regress_test_versioning:
  *
- * Since: 1.32.1
- * Deprecated: 1.33.3: Use foobar instead
- * Stability: Unstable
+ * Since: 1.32.1: Actually, this function was introduced earlier
+ *   than this, but it didn't do anything before this version.
+ * Deprecated: 1.33.3: This function has been deprecated,
+ *   because it sucks. Use foobar instead.
+ * Stability: Unstable: Maybe someday we will find the time
+ *   to stabilize this function. Who knows?
  */
 void
 regress_test_versioning (void)