From 3d5a1478376dc85bfbead43fc66faf340f3f1657 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Corentin=20No=C3=ABl?= Date: Mon, 7 Apr 2025 12:54:38 +0200 Subject: [PATCH] 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. --- libvaladoc/api/girsourcecomment.vala | 4 +-- libvaladoc/api/sourcecomment.vala | 32 +++++++++++++++++-- .../documentation/documentationparser.vala | 3 +- .../importer/girdocumentationimporter.vala | 28 +++++++++++++--- valadoc/treebuilder.vala | 6 ++++ 5 files changed, 63 insertions(+), 10 deletions(-) diff --git a/libvaladoc/api/girsourcecomment.vala b/libvaladoc/api/girsourcecomment.vala index d6ffa5ae6..dc01d5855 100644 --- 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 710e411ed..68f13f068 100644 --- 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 0a5a0d04c..16751bf1c 100644 --- 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 057ab499b..782e7b6db 100644 --- 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 fd485db19..b5d2b525f 100644 --- 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, -- 2.47.2