Bug 552065: Add deprecation information to GIR

	* giscanner/ast.py: Add deprecation attributes.
	* giscanner/girwriter.py: Write out deprecation data.
	* girepository/girparser.c: Relax parsing; deprecated
	attribute now includes freeform string.
	* giscanner/scannerlexer.l: Parse Deprecated.
	* giscanner/transformer.py: Look for deprecated attribute
	on functions.
	* tests/scanner/*: Add a Deprecated test.

svn path=/trunk/; revision=603

8 files changed, 83 insertions, 17 deletions

diff --git a/girepository/girparser.c b/girepository/girparser.c
index b656dc2a..fb95903b 100644
--- a/girepository/girparser.c
+++ b/girepository/girparser.c
@@ -634,7 +634,7 @@ start_glib_boxed (GMarkupParseContext *context,
   ((GIrNode *)boxed)->name = g_strdup (name);
   boxed->gtype_name = g_strdup (typename);
   boxed->gtype_init = g_strdup (typeinit);
-  if (deprecated && strcmp (deprecated, "1") == 0)
+  if (deprecated)
     boxed->deprecated = TRUE;
   else
     boxed->deprecated = FALSE;
@@ -706,7 +706,7 @@ start_function (GMarkupParseContext *context,
   ((GIrNode *)function)->name = g_strdup (name);
   function->symbol = g_strdup (symbol);
   function->parameters = NULL;
-  if (deprecated && strcmp (deprecated, "1") == 0)
+  if (deprecated)
     function->deprecated = TRUE;
   else
     function->deprecated = FALSE;
@@ -1138,7 +1138,7 @@ start_enum (GMarkupParseContext *context,
 	  ((GIrNode *)enum_)->name = g_strdup (name);
 	  enum_->gtype_name = g_strdup (typename);
 	  enum_->gtype_init = g_strdup (typeinit);
-	  if (deprecated && strcmp (deprecated, "1") == 0)
+	  if (deprecated)
 	    enum_->deprecated = TRUE;
 	  else
 	    enum_->deprecated = FALSE;
@@ -1280,7 +1280,7 @@ start_member (GMarkupParseContext *context,
 	  
 	  value_->value = parse_value (value);
 	  
-	  if (deprecated && strcmp (deprecated, "1") == 0)
+	  if (deprecated)
 	    value_->deprecated = TRUE;
 	  else
 	    value_->deprecated = FALSE;
@@ -1330,7 +1330,7 @@ start_constant (GMarkupParseContext *context,
 
 	  ctx->current_typed = (GIrNode*) constant;
 
-	  if (deprecated && strcmp (deprecated, "1") == 0)
+	  if (deprecated)
 	    constant->deprecated = TRUE;
 	  else
 	    constant->deprecated = FALSE;
@@ -1408,7 +1408,7 @@ start_errordomain (GMarkupParseContext *context,
 	  domain->getquark = g_strdup (getquark);
 	  domain->codes = g_strdup (codes);
 
-	  if (deprecated && strcmp (deprecated, "1") == 0)
+	  if (deprecated)
 	    domain->deprecated = TRUE;
 	  else
 	    domain->deprecated = FALSE;
@@ -1460,7 +1460,7 @@ start_interface (GMarkupParseContext *context,
 	  ((GIrNode *)iface)->name = g_strdup (name);
 	  iface->gtype_name = g_strdup (typename);
 	  iface->gtype_init = g_strdup (typeinit);
-	  if (deprecated && strcmp (deprecated, "1") == 0)
+	  if (deprecated)
 	    iface->deprecated = TRUE;
 	  else
 	    iface->deprecated = FALSE;
@@ -1516,7 +1516,7 @@ start_class (GMarkupParseContext *context,
 	  iface->gtype_name = g_strdup (typename);
 	  iface->gtype_init = g_strdup (typeinit);
 	  iface->parent = g_strdup (parent);
-	  if (deprecated && strcmp (deprecated, "1") == 0)
+	  if (deprecated)
 	    iface->deprecated = TRUE;
 	  else
 	    iface->deprecated = FALSE;
@@ -1918,7 +1918,7 @@ start_struct (GMarkupParseContext *context,
       struct_ = (GIrNodeStruct *) g_ir_node_new (G_IR_NODE_STRUCT);
       
       ((GIrNode *)struct_)->name = g_strdup (name);
-      if (deprecated && strcmp (deprecated, "1") == 0)
+      if (deprecated)
 	struct_->deprecated = TRUE;
       else
 	struct_->deprecated = FALSE;
@@ -1969,7 +1969,7 @@ start_union (GMarkupParseContext *context,
 	  ((GIrNode *)union_)->name = g_strdup (name);
 	  union_->gtype_name = g_strdup (typename);
 	  union_->gtype_init = g_strdup (typeinit);
-	  if (deprecated && strcmp (deprecated, "1") == 0)
+	  if (deprecated)
 	    union_->deprecated = TRUE;
 	  else
 	    union_->deprecated = FALSE;
diff --git a/giscanner/ast.py b/giscanner/ast.py
index d8497046..b80559bf 100644
--- a/giscanner/ast.py
+++ b/giscanner/ast.py
@@ -117,6 +117,7 @@ class Node(object):
 
     def __init__(self, name=None):
         self.name = name
+        self.deprecated = None
 
     def __repr__(self):
         return '%s(%r)' % (self.__class__.__name__, self.name)
diff --git a/giscanner/girwriter.py b/giscanner/girwriter.py
index 1eba5005..efa0f01a 100644
--- a/giscanner/girwriter.py
+++ b/giscanner/girwriter.py
@@ -81,6 +81,14 @@ class GIRWriter(XMLWriter):
         else:
             print 'WRITER: Unhandled node', node
 
+    def _append_deprecated(self, node, attrs):
+        if node.deprecated:
+            (deprecated_version, deprecated_str) = node.deprecated
+            attrs.append(('deprecated', deprecated_str.strip()))
+            if deprecated_version:
+                attrs.append(('deprecated-version',
+                              deprecated_version.strip()))
+
     def _write_alias(self, alias):
         attrs = [('name', alias.name), ('target', alias.target)]
         if alias.ctype is not None:
@@ -90,6 +98,7 @@ class GIRWriter(XMLWriter):
     def _write_function(self, func, tag_name='function'):
         attrs = [('name', func.name),
                  ('c:identifier', func.symbol)]
+        self._append_deprecated(func, attrs)
         with self.tagcontext(tag_name, attrs):
             self._write_return_type(func.retval)
             self._write_parameters(func.parameters)
@@ -159,6 +168,7 @@ class GIRWriter(XMLWriter):
     def _write_enum(self, enum):
         attrs = [('name', enum.name),
                  ('c:type', enum.symbol)]
+        self._append_deprecated(enum, attrs)
         tag_name = 'enumeration'
         if isinstance(enum, GLibEnum):
             attrs.extend([('glib:type-name', enum.type_name),
@@ -181,6 +191,7 @@ class GIRWriter(XMLWriter):
     def _write_class(self, node):
         attrs = [('name', node.name),
                  ('c:type', node.ctype)]
+        self._append_deprecated(node, attrs)
         if isinstance(node, Class):
             tag_name = 'class'
             if node.parent is not None:
@@ -229,6 +240,7 @@ class GIRWriter(XMLWriter):
     def _write_callback(self, callback):
         # FIXME: reuse _write_function
         attrs = [('name', callback.name), ('c:type', callback.ctype)]
+        self._append_deprecated(callback, attrs)
         with self.tagcontext('callback', attrs):
             self._write_return_type(callback.retval)
             self._write_parameters(callback.parameters)
@@ -246,6 +258,7 @@ class GIRWriter(XMLWriter):
     def _write_record(self, record):
         attrs = [('name', record.name),
                  ('c:type', record.symbol)]
+        self._append_deprecated(record, attrs)
         if isinstance(record, GLibBoxed):
             attrs.extend(self._boxed_attrs(record))
         with self.tagcontext('record', attrs):
@@ -258,6 +271,7 @@ class GIRWriter(XMLWriter):
     def _write_union(self, union):
         attrs = [('name', union.name),
                  ('c:type', union.symbol)]
+        self._append_deprecated(union, attrs)
         if isinstance(union, GLibBoxed):
             attrs.extend(self._boxed_attrs(union))
         with self.tagcontext('union', attrs):
diff --git a/giscanner/scannerlexer.l b/giscanner/scannerlexer.l
index 0f41637c..98e7c35a 100644
--- a/giscanner/scannerlexer.l
+++ b/giscanner/scannerlexer.l
@@ -207,6 +207,7 @@ parse_gtkdoc (GISourceScanner *scanner,
   GSList *directives;
   GSList *options = NULL;
   char *rname;
+  int n_parts;
 
   i = 0;
   do 
@@ -229,12 +230,24 @@ parse_gtkdoc (GISourceScanner *scanner,
   line[i] = '\0';
 
   parts = g_strsplit (line, ": ", 3);
+  n_parts = g_strv_length (parts);
 
-  if (g_strv_length (parts) >= 2)
+  if (g_ascii_strcasecmp (parts[0], "eprecated") == 0)
+    {
+      if (n_parts == 3)
+	options = g_slist_prepend (options, g_strdup (parts[2]));
+      else if (n_parts == 2)
+	options = g_slist_prepend (options, g_strdup (parts[1]));
+      else
+	options = g_slist_prepend (options, g_strdup (""));
+      name = parts[0];
+      value = NULL;
+    }
+  else if (n_parts >= 2)
     {
       name = parts[0];
 
-      if (g_strv_length (parts) == 3) 
+      if (n_parts == 3) 
         {
           char *ptr = parts[1];
           GString *current = NULL;
@@ -275,12 +288,13 @@ parse_gtkdoc (GISourceScanner *scanner,
     }
 
   /*
-   * This is a special case for return values, name will only be
-   * 'eturn' or a valid name, check the call site.
-   * Context-sensitive parsing would probably be the right way to go
+   * Special cases for global annotations.
+   * Context-sensitive parsing would probably be the right way to go.
    */
   if (g_ascii_strncasecmp ("eturn", name, 5) == 0)
     rname = "return";
+  else if (g_ascii_strncasecmp ("eprecated", name, 9) == 0)
+    rname = "deprecated";
   else
     rname = name;
 
@@ -333,7 +347,7 @@ parse_comment (GISourceScanner *scanner)
       if ((c1 != '*' && c1 != ' '))
           startofline = FALSE;
 
-      if (startofline && (c1 == ' ') && (c2 == '@' || (c2 == 'r') || (c2 == 'R')))
+      if (startofline && (c1 == ' ') && (c2 == '@' || (c2 == 'r') || (c2 == 'R') || (c2 == 'D')))
         {
            c1 = c2;
            c2 = input();
diff --git a/giscanner/transformer.py b/giscanner/transformer.py
index 4c382008..2f96b506 100644
--- a/giscanner/transformer.py
+++ b/giscanner/transformer.py
@@ -222,7 +222,16 @@ class Transformer(object):
         return_ = self._create_return(symbol.base_type.base_type,
                                       directives.get('return', []))
         name = self._strip_namespace_func(symbol.ident)
-        return Function(name, return_, parameters, symbol.ident)
+        func = Function(name, return_, parameters, symbol.ident)
+        deprecated = directives.get('deprecated', False)
+        if deprecated:
+            try:
+                # Split out gtk-doc version
+                func.deprecated = deprecated[0].split(':', 1)
+            except ValueError, e:
+                # No version, just include str
+                func.deprecated = (None, deprecated[0])
+        return func
 
     def _create_source_type(self, source_type):
         if source_type is None:
diff --git a/tests/scanner/annotation-expected.gir b/tests/scanner/annotation-expected.gir
index 8435df10..39fdeb85 100644
--- a/tests/scanner/annotation-expected.gir
+++ b/tests/scanner/annotation-expected.gir
@@ -174,5 +174,18 @@
         </parameter>
       </parameters>
     </function>
+    <function name="object_do_not_use"
+              c:identifier="annotation_object_do_not_use"
+              deprecated="Use annotation_object_create_object() instead."
+              deprecated-version="0.12">
+      <return-value>
+        <type name="GObject.Object" c:type="GObject*"/>
+      </return-value>
+      <parameters>
+        <parameter name="object">
+          <type name="Object" c:type="AnnotationObject*"/>
+        </parameter>
+      </parameters>
+    </function>
   </namespace>
 </repository>
diff --git a/tests/scanner/annotation.c b/tests/scanner/annotation.c
index 04819d06..58a84112 100644
--- a/tests/scanner/annotation.c
+++ b/tests/scanner/annotation.c
@@ -208,3 +208,15 @@ GObject*
 annotation_object_allow_none (AnnotationObject *object, gchar *allow_none)
 {
 }
+
+/**
+ * annotation_object_do_not_use: 
+ * @object: a #GObject
+ *
+ * Deprecated: 0.12: Use annotation_object_create_object() instead.
+ **/
+GObject*
+annotation_object_do_not_use (AnnotationObject *object)
+{
+  return NULL;
+}
diff --git a/tests/scanner/annotation.h b/tests/scanner/annotation.h
index 02a51634..2e2e4431 100644
--- a/tests/scanner/annotation.h
+++ b/tests/scanner/annotation.h
@@ -38,4 +38,7 @@ gint     annotation_object_calleesowns  (AnnotationObject *object,
 GList*   annotation_object_get_strings  (AnnotationObject *object);
 GSList*  annotation_object_get_objects  (AnnotationObject *object);
 
+GObject* annotation_object_do_not_use   (AnnotationObject *object);
+
+
 #endif /* __ANNOTATION_OBJECT_H__ */