libvaladoc: Introduce support for different documentation formats

Many libraries are now using gi-docgen and we are starting to see the doc:format
entry in the .girs.

diff --git a/libvaladoc/api/girsourcecomment.vala b/libvaladoc/api/girsourcecomment.vala
index d6ffa5ae6ab35fcfec580a0e3f198fcb2bd46bd6..dc01d5855c99ddedb495998ddcc51d185f98fd57 100644 (file)
--- a/libvaladoc/api/girsourcecomment.vala
+++ b/libvaladoc/api/girsourcecomment.vala
@@ -50,8 +50,8 @@ public class Valadoc.Api.GirSourceComment : SourceComment {
                return parameters.get (param_name);
        }
 
-       public GirSourceComment (string content, SourceFile file, int first_line, int first_column, int last_line, int last_column) {
-               base (content, file, first_line, first_column, last_line, last_column);
+       public GirSourceComment (string content, SourceComment.Format format, SourceFile file, int first_line, int first_column, int last_line, int last_column) {
+               base (content, format, file, first_line, first_column, last_line, last_column);
        }
 }
 

diff --git a/libvaladoc/api/sourcecomment.vala b/libvaladoc/api/sourcecomment.vala
index 710e411ed51b7896a1351353dfcf2abc5940faf5..68f13f068872e1532a933fa34ea8282e87105313 100644 (file)
--- a/libvaladoc/api/sourcecomment.vala
+++ b/libvaladoc/api/sourcecomment.vala
@@ -25,6 +25,24 @@
  * A documentation comment used by valadoc
  */
 public class Valadoc.Api.SourceComment {
+       public enum Format {
+               UNKNOWN,
+               GI_DOCGEN,
+               GTK_DOC_MARKDOWN,
+               GTK_DOC_DOCBOOK,
+               HOTDOC;
+
+               public static Format from_string (string val) {
+                       var enum_class = (EnumClass) typeof(Format).class_ref ();
+                       unowned GLib.EnumValue? enum_value = enum_class.get_value_by_nick (val);
+                       if (enum_value != null) {
+                               return (Format) enum_value.value;
+                       }
+
+                       return Format.UNKNOWN;
+               }
+       }
+
        public SourceFile file {
                private set;
                get;
@@ -38,6 +56,14 @@ public class Valadoc.Api.SourceComment {
                get;
        }
 
+       /**
+        * The format of the documentation comment.
+        */
+       public Format format {
+               private set;
+               get;
+       }
+
        /**
         * The first line number of the referenced source code.
         */
@@ -70,14 +96,16 @@ public class Valadoc.Api.SourceComment {
                get;
        }
 
-       public SourceComment (string content, SourceFile file, int first_line, int first_column,
-                                                 int last_line, int last_column)
+       public SourceComment (string content, Format format, SourceFile file,
+                                                int first_line, int first_column,
+                                                int last_line, int last_column)
        {
                this.first_column = first_column;
                this.last_column = last_column;
                this.first_line = first_line;
                this.last_line = last_line;
                this.content = content;
+               this.format = format;
                this.file = file;
        }
 }

diff --git a/libvaladoc/documentation/documentationparser.vala b/libvaladoc/documentation/documentationparser.vala
index 0a5a0d04c643c13a4e12e1858406238c7e772ce1..16751bf1c5a2b47c7e8eb7e38eec4852e502581e 100644 (file)
--- a/libvaladoc/documentation/documentationparser.vala
+++ b/libvaladoc/documentation/documentationparser.vala
@@ -80,7 +80,8 @@ public class Valadoc.DocumentationParser : Object, ResourceLocator {
                        Api.GirSourceComment gir_comment = (Api.GirSourceComment) comment;
                        GirMetaData metadata = get_metadata_for_comment (gir_comment);
 
-                       if (metadata.is_docbook) {
+                       //TODO Handle more documentation formats
+                       if (metadata.is_docbook || comment.format == Api.SourceComment.Format.GTK_DOC_DOCBOOK) {
                                Comment doc_comment = gtkdoc_parser.parse (element, gir_comment, metadata, id_registrar);
                                return doc_comment;
                        } else {

diff --git a/libvaladoc/importer/girdocumentationimporter.vala b/libvaladoc/importer/girdocumentationimporter.vala
index 057ab499b62dca8300107e3c3ccd39675506fc20..782e7b6db6c5b20cc0805e58dacccdc615d6c3e0 100644 (file)
--- a/libvaladoc/importer/girdocumentationimporter.vala
+++ b/libvaladoc/importer/girdocumentationimporter.vala
@@ -38,6 +38,7 @@ public class Valadoc.Importer.GirDocumentationImporter : DocumentationImporter {
        private Vala.SourceLocation begin;
        private Vala.SourceLocation end;
        private Vala.MarkupReader reader;
+       private Api.SourceComment.Format documentation_format;
 
        private DocumentationParser parser;
        private Api.SourceFile file;
@@ -217,6 +218,8 @@ public class Valadoc.Importer.GirDocumentationImporter : DocumentationImporter {
                                parse_package ();
                        } else if (reader.name == "c:include") {
                                parse_c_include ();
+                       } else if (reader.name == "doc:format") {
+                               parse_doc_format ();
                        } else {
                                // error
                                error ("unknown child element `%s' in `repository'".printf (reader.name));
@@ -247,6 +250,21 @@ public class Valadoc.Importer.GirDocumentationImporter : DocumentationImporter {
                end_element ("c:include");
        }
 
+       private void parse_doc_format () {
+               start_element ("doc:format");
+               var format_name = reader.get_attribute ("name");
+               if (format_name != null) {
+                       documentation_format = Api.SourceComment.Format.from_string (format_name);
+
+                       if (documentation_format == Api.SourceComment.Format.UNKNOWN && format_name != "unknown") {
+                               warning ("Unknown documentation format `%s'".printf (format_name));
+                       }
+               }
+
+               next ();
+               end_element ("doc:format");
+       }
+
        private void skip_element () {
                next ();
 
@@ -331,7 +349,7 @@ public class Valadoc.Importer.GirDocumentationImporter : DocumentationImporter {
                                next ();
 
                                if (current_token == Vala.MarkupTokenType.TEXT) {
-                                       comment = new Api.GirSourceComment (reader.content, file, begin.line,
+                                       comment = new Api.GirSourceComment (reader.content, documentation_format, file, begin.line,
                                                                                                                begin.column, end.line, end.column);
                                        next ();
                                }
@@ -372,7 +390,7 @@ public class Valadoc.Importer.GirDocumentationImporter : DocumentationImporter {
                Api.SourceComment? comment = null;
 
                if (current_token == Vala.MarkupTokenType.TEXT) {
-                       comment = new Api.SourceComment (reader.content, file, begin.line,
+                       comment = new Api.SourceComment (reader.content, documentation_format, file, begin.line,
                                                                                         begin.column, end.line, end.column);
                        next ();
                }
@@ -697,7 +715,7 @@ public class Valadoc.Importer.GirDocumentationImporter : DocumentationImporter {
                        parse_return_value (out return_comment, out array_length_ret);
                        if (return_comment != null) {
                                if (comment == null) {
-                                       comment = new Api.GirSourceComment ("", file, begin.line, begin.column,
+                                       comment = new Api.GirSourceComment ("", documentation_format, file, begin.line, begin.column,
                                                                                                                end.line, end.column);
                                }
                                comment.return_comment = return_comment;
@@ -719,7 +737,7 @@ public class Valadoc.Importer.GirDocumentationImporter : DocumentationImporter {
 
                                if (param_comment != null) {
                                        if (comment == null) {
-                                               comment = new Api.GirSourceComment ("", file, begin.line, begin.column,
+                                               comment = new Api.GirSourceComment ("", documentation_format, file, begin.line, begin.column,
                                                                                                                        end.line, end.column);
                                        }
 
@@ -753,7 +771,7 @@ public class Valadoc.Importer.GirDocumentationImporter : DocumentationImporter {
 
                                if (param_comment != null) {
                                        if (comment == null) {
-                                               comment = new Api.GirSourceComment ("", file, begin.line, begin.column,
+                                               comment = new Api.GirSourceComment ("", documentation_format, file, begin.line, begin.column,
                                                                                                                        end.line, end.column);
                                        }
 

diff --git a/valadoc/treebuilder.vala b/valadoc/treebuilder.vala
index fd485db193359c450f3e2344612468017ca2068d..b5d2b525fbd3b72f35ca28e5ae81f98613e39e74 100644 (file)
--- a/valadoc/treebuilder.vala
+++ b/valadoc/treebuilder.vala
@@ -85,6 +85,7 @@ public class Valadoc.TreeBuilder : Vala.CodeVisitor {
                                                Vala.SourceReference pos = c.source_reference;
                                                if (c is Vala.GirComment) {
                                                        comment = new GirSourceComment (c.content,
+                                                                                                                       Api.SourceComment.Format.UNKNOWN,
                                                                                                                        file,
                                                                                                                        pos.begin.line,
                                                                                                                        pos.begin.column,
@@ -92,6 +93,7 @@ public class Valadoc.TreeBuilder : Vala.CodeVisitor {
                                                                                                                        pos.end.column);
                                                } else {
                                                        comment = new SourceComment (c.content,
+                                                                                                                Api.SourceComment.Format.UNKNOWN,
                                                                                                                 file,
                                                                                                                 pos.begin.line,
                                                                                                                 pos.begin.column,
@@ -221,6 +223,7 @@ public class Valadoc.TreeBuilder : Vala.CodeVisitor {
                        SourceFile file = files.get (pos.file);
                        if (comment is Vala.GirComment) {
                                var tmp = new GirSourceComment (comment.content,
+                                                                                               Api.SourceComment.Format.UNKNOWN,
                                                                                                file,
                                                                                                pos.begin.line,
                                                                                                pos.begin.column,
@@ -229,6 +232,7 @@ public class Valadoc.TreeBuilder : Vala.CodeVisitor {
                                if (((Vala.GirComment) comment).return_content != null) {
                                        Vala.SourceReference return_pos = ((Vala.GirComment) comment).return_content.source_reference;
                                        tmp.return_comment = new SourceComment (((Vala.GirComment) comment).return_content.content,
+                                                                                                                       Api.SourceComment.Format.UNKNOWN,
                                                                                                                        file,
                                                                                                                        return_pos.begin.line,
                                                                                                                        return_pos.begin.column,
@@ -241,6 +245,7 @@ public class Valadoc.TreeBuilder : Vala.CodeVisitor {
                                        Vala.Comment vala_param = it.get_value ();
                                        Vala.SourceReference param_pos = vala_param.source_reference;
                                        var param_comment = new SourceComment (vala_param.content,
+                                                                                                                  Api.SourceComment.Format.UNKNOWN,
                                                                                                                   file,
                                                                                                                   param_pos.begin.line,
                                                                                                                   param_pos.begin.column,
@@ -251,6 +256,7 @@ public class Valadoc.TreeBuilder : Vala.CodeVisitor {
                                return tmp;
                        } else {
                                return new SourceComment (comment.content,
+                                                                                 Api.SourceComment.Format.UNKNOWN,
                                                                                  file,
                                                                                  pos.begin.line,
                                                                                  pos.begin.column,