[valadoc] C1; 2403; 0cdoclets/gtkdoc: Improve generation of SECTION comments
- From: Luca Bruno <lucabru src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [valadoc] C1; 2403; 0cdoclets/gtkdoc: Improve generation of SECTION comments
- Date: Thu, 19 Aug 2010 17:55:56 +0000 (UTC)
commit 2b811d0881ec17e4c297c1aaef6613e749bc415a
Author: Luca Bruno <lethalman88 gmail com>
Date: Thu Aug 19 18:32:01 2010 +0200
C1;2403;0cdoclets/gtkdoc: Improve generation of SECTION comments
src/doclets/gtkdoc/doclet.vala | 1 -
src/doclets/gtkdoc/generator.vala | 74 +++++++++++++++++++++++++++----------
2 files changed, 54 insertions(+), 21 deletions(-)
---
diff --git a/src/doclets/gtkdoc/doclet.vala b/src/doclets/gtkdoc/doclet.vala
index 1153da3..9d2c1f6 100644
--- a/src/doclets/gtkdoc/doclet.vala
+++ b/src/doclets/gtkdoc/doclet.vala
@@ -195,7 +195,6 @@ public class Gtkdoc.Director : Valadoc.Doclet, Object {
"--module", settings.pkg_name,
"--output-dir", output_dir,
"--rebuild-sections", "--rebuild-types" };
- string ignored = "";
foreach (var header in headers) {
args += header;
diff --git a/src/doclets/gtkdoc/generator.vala b/src/doclets/gtkdoc/generator.vala
index 741a561..72e0ff3 100644
--- a/src/doclets/gtkdoc/generator.vala
+++ b/src/doclets/gtkdoc/generator.vala
@@ -27,6 +27,8 @@ using Valadoc.Content;
public class Gtkdoc.Generator : Api.Visitor {
class FileData {
public string filename;
+ public string title;
+ public GComment section_comment;
public Gee.List<GComment> comments;
public Gee.List<string> section_lines;
}
@@ -67,6 +69,11 @@ public class Gtkdoc.Generator : Api.Visitor {
return false;
}
+ // Gtkdoc SECTION
+ if (file_data.section_comment != null) {
+ cwriter.write_line (file_data.section_comment.to_string ());
+ }
+
foreach (var comment in file_data.comments) {
cwriter.write_line (comment.to_string ());
}
@@ -75,6 +82,9 @@ public class Gtkdoc.Generator : Api.Visitor {
// sections
sections_writer.write_line ("<SECTION>");
sections_writer.write_line ("<FILE>%s</FILE>".printf (basename));
+ if (file_data.title != null) {
+ sections_writer.write_line ("<TITLE>%s</TITLE>".printf (file_data.title));
+ }
foreach (var section_line in file_data.section_lines) {
sections_writer.write_line (section_line);
@@ -95,6 +105,8 @@ public class Gtkdoc.Generator : Api.Visitor {
if (file_data == null) {
file_data = new FileData ();
file_data.filename = filename;
+ file_data.title = null;
+ file_data.section_comment = null;
file_data.comments = new Gee.LinkedList<GComment>();
file_data.section_lines = new Gee.LinkedList<string>();
files_data[filename] = file_data;
@@ -140,7 +152,28 @@ public class Gtkdoc.Generator : Api.Visitor {
return headers;
}
- private GComment create_gcomment (string symbol, Comment? comment, bool short_description = false, string[]? returns_annotations = null, bool is_dbus = false) {
+ private void set_section_comment (string filename, string section_name, Comment? comment) {
+ var file_data = get_file_data (filename);
+ if (file_data.title == null) {
+ file_data.title = section_name;
+ }
+ if (comment == null) {
+ return;
+ }
+ if (file_data.section_comment != null) {
+ // already have a section comment
+ return;
+ }
+
+ var gcomment = create_gcomment ("SECTION:%s".printf (get_section (filename)), comment);
+ if (gcomment.brief_comment != null) {
+ gcomment.headers.insert (0, new Header ("@short_description", gcomment.brief_comment));
+ gcomment.brief_comment = null;
+ }
+ file_data.section_comment = gcomment;
+ }
+
+ private GComment create_gcomment (string symbol, Comment? comment, string[]? returns_annotations = null, bool is_dbus = false) {
var converter = new Gtkdoc.CommentConverter ();
if (comment != null) {
converter.convert (comment, is_dbus);
@@ -152,12 +185,7 @@ public class Gtkdoc.Generator : Api.Visitor {
gcomment.returns_annotations = returns_annotations;
gcomment.see_also = converter.see_also;
- if (converter.brief_comment != null && short_description) {
- var header = new Header ("@short_description", converter.brief_comment);
- gcomment.headers.add (header);
- } else {
- gcomment.brief_comment = converter.brief_comment;
- }
+ gcomment.brief_comment = converter.brief_comment;
gcomment.long_comment = converter.long_comment;
gcomment.headers.add_all (merge_headers (converter.headers, current_headers));
@@ -165,27 +193,24 @@ public class Gtkdoc.Generator : Api.Visitor {
return gcomment;
}
- private GComment? add_comment (string filename, string symbol, Comment? comment, bool short_description = false) {
+ private GComment? add_comment (string filename, string symbol, Comment? comment) {
if (comment == null) {
return null;
}
var file_data = get_file_data (filename);
- var gcomment = create_gcomment (symbol, comment, short_description);
+ var gcomment = create_gcomment (symbol, comment);
file_data.comments.add (gcomment);
return gcomment;
}
- private GComment? add_symbol (string filename, string cname, Comment? comment = null, string? symbol = null, bool title = false, bool short_description = false, string[]? returns_annotations = null) {
+ private GComment? add_symbol (string filename, string cname, Comment? comment = null, string? symbol = null, string[]? returns_annotations = null) {
var file_data = get_file_data (filename);
- if (title) {
- file_data.section_lines.add ("<TITLE>%s</TITLE>".printf (cname));
- }
file_data.section_lines.add (cname);
if (comment != null || (current_headers != null && current_headers.size > 0)) {
- var gcomment = create_gcomment (symbol ?? cname, comment, short_description, returns_annotations);
+ var gcomment = create_gcomment (symbol ?? cname, comment, returns_annotations);
file_data.comments.add (gcomment);
return gcomment;
}
@@ -254,7 +279,7 @@ public class Gtkdoc.Generator : Api.Visitor {
public override void visit_namespace (Api.Namespace ns) {
if (ns.get_filename () != null) {
- add_comment (ns.get_filename(), "SECTION:%s".printf (get_section (ns.get_filename ())), ns.documentation, true);
+ set_section_comment (ns.get_filename (), get_section (ns.get_filename ()), ns.documentation);
}
ns.accept_all_children (this);
@@ -271,8 +296,12 @@ public class Gtkdoc.Generator : Api.Visitor {
if (iface.get_dbus_name () != null) {
current_dbus_interface = new DBus.Interface (settings.pkg_name, iface.get_dbus_name ());
}
+
iface.accept_all_children (this);
- add_symbol (iface.get_filename(), iface.get_cname(), iface.documentation, null, true);
+
+ add_symbol (iface.get_filename(), iface.get_cname(), iface.documentation, null);
+ set_section_comment (iface.get_filename(), iface.get_cname(), iface.documentation);
+
if (current_dbus_interface != null) {
current_dbus_interface.write (settings);
dbus_interfaces.add (current_dbus_interface);
@@ -296,8 +325,13 @@ public class Gtkdoc.Generator : Api.Visitor {
if (cl.get_dbus_name () != null) {
current_dbus_interface = new DBus.Interface (settings.pkg_name, cl.get_dbus_name ());
}
+
+
cl.accept_all_children (this);
- add_symbol (cl.get_filename(), cl.get_cname(), cl.documentation, null, true);
+
+ add_symbol (cl.get_filename(), cl.get_cname(), cl.documentation, null);
+ set_section_comment (cl.get_filename(), cl.get_cname(), cl.documentation);
+
if (current_dbus_interface != null) {
current_dbus_interface.write (settings);
dbus_interfaces.add (current_dbus_interface);
@@ -454,7 +488,7 @@ public class Gtkdoc.Generator : Api.Visitor {
gcomment.headers.insert (0, new Header ("@%s".printf (to_lower_case (((Api.Node)sig.parent).name)),
"the %s".printf (get_docbook_link (sig.parent))));
if (current_dbus_interface != null && sig.is_dbus_visible) {
- var dbuscomment = create_gcomment (sig.get_dbus_name (), sig.documentation, false, null, true);
+ var dbuscomment = create_gcomment (sig.get_dbus_name (), sig.documentation, null, true);
current_dbus_member.comment = dbuscomment;
current_dbus_interface.add_signal (current_dbus_member);
}
@@ -503,7 +537,7 @@ public class Gtkdoc.Generator : Api.Visitor {
see_also += get_docbook_link (m, false, true);
gcomment.see_also = see_also;
} else {
- add_symbol (m.get_filename(), m.get_cname (), m.documentation, null, false, false, annotations);
+ add_symbol (m.get_filename(), m.get_cname (), m.documentation, null, annotations);
}
if (current_dbus_interface != null && m.is_dbus_visible && !m.is_constructor) {
@@ -511,7 +545,7 @@ public class Gtkdoc.Generator : Api.Visitor {
var dresult = new DBus.Parameter (m.get_dbus_result_name (), m.return_type.get_dbus_type_signature (), DBus.Parameter.Direction.OUT);
current_dbus_member.add_parameter (dresult);
}
- var gcomment = create_gcomment (m.get_dbus_name (), m.documentation, false, null, true);
+ var gcomment = create_gcomment (m.get_dbus_name (), m.documentation, null, true);
current_dbus_member.comment = gcomment;
current_dbus_interface.add_method (current_dbus_member);
}
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]