[valadoc] gir-importer: Add support for <instance-parameter>

[Florian Brosch <flobrosch src gnome org>]

commit 5dde44de84cc90ad8f8fe554deaa64597e54ab64
Author: Florian Brosch <flo brosch gmail com>
Date:   Tue Mar 19 21:49:46 2013 +0100

    gir-importer: Add support for <instance-parameter>

 src/libvaladoc/api/girsourcecomment.vala           |    1 +
 .../documentation/gtkdoccommentparser.vala         |   63 ++++++++++++--------
 .../importer/girdocumentationimporter.vala         |   20 ++++++
 src/libvaladoc/taglets/tagletparam.vala            |    4 +-
 4 files changed, 62 insertions(+), 26 deletions(-)
---
diff --git a/src/libvaladoc/api/girsourcecomment.vala b/src/libvaladoc/api/girsourcecomment.vala
index e554092..77bfb5f 100644
--- a/src/libvaladoc/api/girsourcecomment.vala
+++ b/src/libvaladoc/api/girsourcecomment.vala
@@ -30,6 +30,7 @@ using Gee;
 public class Valadoc.Api.GirSourceComment : SourceComment {
        private Map<string, SourceComment> parameters = new HashMap<string, SourceComment> ();
 
+       public string? instance_param_name { set; get; }
        public SourceComment return_comment { set; get; }
 
        public MapIterator<string, SourceComment> parameter_iterator () {
diff --git a/src/libvaladoc/documentation/gtkdoccommentparser.vala 
b/src/libvaladoc/documentation/gtkdoccommentparser.vala
index 7b97bef..5e0ce5b 100644
--- a/src/libvaladoc/documentation/gtkdoccommentparser.vala
+++ b/src/libvaladoc/documentation/gtkdoccommentparser.vala
@@ -279,6 +279,12 @@ public class Valadoc.Gtkdoc.Parser : Object, ResourceLocator {
                        }
 
                        taglet.parameter_name = iter.get_key ();
+
+                       if (taglet.parameter_name == gir_comment.instance_param_name) {
+                               taglet.parameter_name = "this";
+                               taglet.is_c_self_param = true;
+                       }
+
                        comment.taglets.add (taglet);
                }
 
@@ -1718,32 +1724,39 @@ public class Valadoc.Gtkdoc.Parser : Object, ResourceLocator {
                                run.content.add (this.create_type_link (current.content));
                                next ();
                        } else if (current.type == TokenType.GTKDOC_PARAM) {
-                               string? param_array_name;
-                               bool is_return_type_len;
-                               string? param_name;
-
-                               string? cname = resolve_parameter_ctype (current.content, out param_name, out 
param_array_name, out is_return_type_len);
-                               Run current_run = factory.create_run (Run.Style.MONOSPACED);
-                               run.content.add (current_run);
-
-                               if (is_return_type_len) {
-                                       Run keyword_run = factory.create_run (Run.Style.LANG_KEYWORD);
-                                       keyword_run.content.add (factory.create_text ("return"));
-                                       current_run.content.add (keyword_run);
-
-                                       current_run.content.add (factory.create_text (".length"));
-                               } else if (param_array_name != null) {
-                                       current_run.content.add (factory.create_text (param_array_name + 
".length"));
+                               if (current.content == instance_param_name) {
+                                       Content.Run keyword_run = factory.create_run 
(Content.Run.Style.LANG_KEYWORD);
+                                       Content.Text text = factory.create_text ("this");
+                                       keyword_run.content.add (text);
+                                       run.content.add (keyword_run);
                                } else {
-                                       current_run.content.add (factory.create_text (param_name));
-                               }
-
-                               if (cname != null) {
-                                       run.content.add (factory.create_text ("."));
-
-                                       Taglets.Link link = factory.create_taglet ("link") as Taglets.Link;
-                                       link.symbol_name = cname;
-                                       run.content.add (link);
+                                       string? param_array_name;
+                                       bool is_return_type_len;
+                                       string? param_name;
+
+                                       string? cname = resolve_parameter_ctype (current.content, out 
param_name, out param_array_name, out is_return_type_len);
+                                       Run current_run = factory.create_run (Run.Style.MONOSPACED);
+                                       run.content.add (current_run);
+
+                                       if (is_return_type_len) {
+                                               Run keyword_run = factory.create_run (Run.Style.LANG_KEYWORD);
+                                               keyword_run.content.add (factory.create_text ("return"));
+                                               current_run.content.add (keyword_run);
+
+                                               current_run.content.add (factory.create_text (".length"));
+                                       } else if (param_array_name != null) {
+                                               current_run.content.add (factory.create_text 
(param_array_name + ".length"));
+                                       } else {
+                                               current_run.content.add (factory.create_text (param_name));
+                                       }
+
+                                       if (cname != null) {
+                                               run.content.add (factory.create_text ("."));
+
+                                               Taglets.Link link = factory.create_taglet ("link") as 
Taglets.Link;
+                                               link.symbol_name = cname;
+                                               run.content.add (link);
+                                       }
                                }
                                next ();
                        } else if (current.type == TokenType.GTKDOC_SIGNAL) {
diff --git a/src/libvaladoc/importer/girdocumentationimporter.vala 
b/src/libvaladoc/importer/girdocumentationimporter.vala
index 73d7218..02f9e85 100644
--- a/src/libvaladoc/importer/girdocumentationimporter.vala
+++ b/src/libvaladoc/importer/girdocumentationimporter.vala
@@ -663,6 +663,25 @@ public class Valadoc.Importer.GirDocumentationImporter : DocumentationImporter {
                        start_element ("parameters");
                        next ();
 
+                       if (current_token == MarkupTokenType.START_ELEMENT && reader.name == 
"instance-parameter") {
+                               string instance_param_name = reader.get_attribute ("name");
+                               next ();
+
+                               Api.SourceComment? param_comment = parse_doc ();
+                               parse_type (null);
+                               end_element ("instance-parameter");
+
+                               if (param_comment != null) {
+                                       if (comment == null) {
+                                               comment = new Api.GirSourceComment ("", file, begin.line, 
begin.column,
+                                                                                                             
          end.line, end.column);
+                                       }
+
+                                       comment.add_parameter_content (instance_param_name, param_comment);
+                                       comment.instance_param_name = instance_param_name;
+                               }
+                       }
+
                        for (int pcount = 0; current_token == MarkupTokenType.START_ELEMENT; pcount++) {
                                Api.SourceComment? param_comment;
                                int array_length_pos;
@@ -700,6 +719,7 @@ public class Valadoc.Importer.GirDocumentationImporter : DocumentationImporter {
 
                attach_comment (c_identifier, comment, param_names, destroy_notifies, closures,
                                                array_lengths, array_length_ret);
+
                end_element (element_name);
        }
 
diff --git a/src/libvaladoc/taglets/tagletparam.vala b/src/libvaladoc/taglets/tagletparam.vala
index 1fa3007..b2a42be 100644
--- a/src/libvaladoc/taglets/tagletparam.vala
+++ b/src/libvaladoc/taglets/tagletparam.vala
@@ -32,6 +32,8 @@ public class Valadoc.Taglets.Param : InlineContent, Taglet, Block {
 
        public int position { private set; get; default = -1; }
 
+       public bool is_c_self_param { internal set; get; }
+
        public Rule? get_parser_rule (Rule run_rule) {
                return Rule.seq ({
                        Rule.option ({ Rule.many ({ TokenType.SPACE }) }),
@@ -105,7 +107,7 @@ public class Valadoc.Taglets.Param : InlineContent, Taglet, Block {
                        if (is_implicit) {
                                reporter.simple_note ("%s: %s: @param: warning: Implicit parameter `%s' 
exposed in documentation",
                                                                          file_path, container.get_full_name 
(), parameter_name);
-                       } else {
+                       } else if (!is_c_self_param) {
                                reporter.simple_warning ("%s: %s: @param: warning: Unknown parameter `%s'",
                                                                                 file_path, 
container.get_full_name (), parameter_name);
                        }