Skip to content

Commit

Permalink
support gi-docgen comments
Browse files Browse the repository at this point in the history
  • Loading branch information
@Prince781
Prince781 committed Nov 28, 2021
1 parent 971a9d8 commit 2e9d1a9
Show file tree
Hide file tree
Showing 2 changed files with 80 additions and 11 deletions.
22 changes: 16 additions & 6 deletions src/documentation/doccomment.vala
View file
Original file line number Diff line number Diff line change
Expand Up @@ -49,22 +49,32 @@ class Vls.DocComment {
}

/**
* Render a GTK-Doc-formatted comment into Markdown.
* Render a GTK-Doc- or gi-docgen-formatted comment into Markdown.
*
* see [[https://developer.gnome.org/gtk-doc-manual/stable/documenting_syntax.html.en]]
* and [[https://gnome.pages.gitlab.gnome.org/gi-docgen/linking.html]]
*
* @param comment A comment in GTK-Doc format
* @param comment A comment in GTK-Doc or gi-docgen format
* @param documentation Holds GIR documentation and renders the comment
* @param compilation The current compilation that is the context of the comment
*/
public DocComment.from_gir_comment (Vala.Comment comment, GirDocumentation documentation, Compilation compilation) throws RegexError {
body = documentation.render_gtk_doc_comment (comment, compilation);
Regex regex = /\[(\w+)@(\w+(\.\w+)*)(::?([\w\-]+))?\]/;
body = regex.match (comment.content) ?
documentation.render_gi_docgen_comment (comment, compilation) :
documentation.render_gtk_doc_comment (comment, compilation);
if (comment is Vala.GirComment) {
var gir_comment = (Vala.GirComment) comment;
for (var it = gir_comment.parameter_iterator (); it.next (); )
parameters[it.get_key ()] = documentation.render_gtk_doc_comment (it.get_value (), compilation);
for (var it = gir_comment.parameter_iterator (); it.next (); ) {
Vala.Comment param_comment = it.get_value ();
parameters[it.get_key ()] = regex.match (param_comment.content) ?
documentation.render_gi_docgen_comment (param_comment, compilation) :
documentation.render_gtk_doc_comment (param_comment, compilation);
}
if (gir_comment.return_content != null)
return_body = documentation.render_gtk_doc_comment (gir_comment.return_content, compilation);
return_body = regex.match (gir_comment.return_content.content) ?
documentation.render_gi_docgen_comment (gir_comment.return_content, compilation) :
documentation.render_gtk_doc_comment (gir_comment.return_content, compilation);
}
}

Expand Down
69 changes: 64 additions & 5 deletions src/documentation/girdocumentation.vala
View file
Original file line number Diff line number Diff line change
Expand Up @@ -192,13 +192,63 @@ class Vls.GirDocumentation {
}

/**
* Decide to render a GTK-Doc formatted comment into Markdown.
* Renders a gi-docgen formatted comment into Markdown.
*
* see https://developer.gnome.org/gtk-doc-manual/stable/documenting_syntax.html.en
* see [[https://gnome.pages.gitlab.gnome.org/gi-docgen/linking.html]]
*/
public string render_gtk_doc_comment (Vala.Comment comment, Compilation compilation) throws GLib.RegexError {
public string render_gi_docgen_comment (Vala.Comment comment, Compilation compilation) throws GLib.RegexError {
string comment_data = comment.content;

comment_data = /\[(\w+)@(\w+(\.\w+)*)(::?([\w+\-]+))?\]/
.replace_eval (comment_data, comment_data.length, 0, 0, (match_info, result) => {
// string link_type = (!) match_info.fetch (1);
string symbol_full = (!) match_info.fetch (2);
string? signal_or_property_name = match_info.fetch (5);
if (signal_or_property_name != null && signal_or_property_name.length > 0)
symbol_full += "." + signal_or_property_name.replace ("-", "_");
Vala.Symbol? vala_symbol = CodeHelp.lookup_symbol_full_name (symbol_full, compilation.code_context.root.scope);

if (vala_symbol == null) {
result.append ("**");
result.append (symbol_full);
result.append ("**");
} else {
var sym_sb = new StringBuilder ();
Vala.Symbol? previous_sym = null;
for (var current_sym = vala_symbol;
current_sym != null && current_sym.name != null;
current_sym = current_sym.parent_symbol) {
if (current_sym is Vala.CreationMethod) {
sym_sb.prepend (current_sym.name == ".new" ? current_sym.parent_symbol.name : current_sym.name);
} else {
if (current_sym != vala_symbol) {
if (previous_sym is Vala.CreationMethod)
sym_sb.prepend ("::");
else
sym_sb.prepend_c ('.');
}
sym_sb.prepend (current_sym.name);
}
previous_sym = current_sym;
}
result.append ("**");
result.append (sym_sb.str);
if (vala_symbol is Vala.Callable && !(vala_symbol is Vala.Delegate))
result.append ("()");
result.append ("**");
}
return false;
});

return render_gtk_doc_content (comment_data, comment, compilation);
}

/**
* Renders @comment_data possibly after it has been processed.
*/
public string render_gtk_doc_content (string content, Vala.Comment comment, Compilation compilation) throws GLib.RegexError {
string comment_data = content; // FIXME: workaround for valac codegen bug

// replace code blocks
comment_data = /\|\[(<!-- language="(\w+)" -->)?((.|\s)*?)\]\|/
.replace_eval (comment_data, comment_data.length, 0, 0, (match_info, result) => {
Expand Down Expand Up @@ -269,7 +319,7 @@ class Vls.GirDocumentation {
debug ("found new GTK-Doc dir for GIR %s%s: %s", gir_package_name, vapi_pkg_name != null ? @" (VAPI $vapi_pkg_name)" : "", gtkdoc_dir);
}
}

if (gtkdoc_dir != null) {
// substitute image URLs
// substitute relative paths in GIR comments for absolute paths to GTK-Doc resources
Expand All @@ -281,7 +331,7 @@ class Vls.GirDocumentation {
result.append ("![");
result.append (link_label);
result.append ("](");
if (!Path.is_absolute (link_href))
if (link_href.length > 0 && !Path.is_absolute (link_href))
link_href = Path.build_filename (gtkdoc_dir, link_href);
result.append (link_href);
result.append_c (')');
Expand Down Expand Up @@ -410,6 +460,15 @@ class Vls.GirDocumentation {
return comment_data;
}

/**
* Renders a GTK-Doc formatted comment into Markdown.
*
* see [[https://developer.gnome.org/gtk-doc-manual/stable/documenting_syntax.html.en]]
*/
public string render_gtk_doc_comment (Vala.Comment comment, Compilation compilation) throws GLib.RegexError {
return render_gtk_doc_content (comment.content, comment, compilation);
}

/**
* Find the GIR symbol related to @sym
*/
Expand Down

0 comments on commit 2e9d1a9

Please sign in to comment.