From: Florian Brosch Date: Fri, 12 Aug 2011 00:32:51 +0000 (+0200) Subject: libvaladoc/html: Mark deprecated symbols X-Git-Tag: 0.37.1~3^2~298 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=bc2b84e6854c7cf7e935a42dbfd6aa3e867a38f2;p=thirdparty%2Fvala.git libvaladoc/html: Mark deprecated symbols --- diff --git a/icons/devhelpstyle.css b/icons/devhelpstyle.css index 19392d112..fa181e222 100644 --- a/icons/devhelpstyle.css +++ b/icons/devhelpstyle.css @@ -530,3 +530,6 @@ ul.no_bullet li { .package_note { } +.deprecated { + text-decoration:line-through; +} diff --git a/icons/style.css b/icons/style.css index 045641760..e556fbd6d 100644 --- a/icons/style.css +++ b/icons/style.css @@ -542,3 +542,6 @@ ul.no_bullet li { .package_note { } +.deprecated { + text-decoration:line-through; +} diff --git a/icons/wikistyle.css b/icons/wikistyle.css index 9c878ce09..56ca6bc73 100644 --- a/icons/wikistyle.css +++ b/icons/wikistyle.css @@ -495,3 +495,6 @@ ul.no_bullet li { color: #ff01ff; } +.deprecated { + text-decoration:line-through; +} diff --git a/src/libvaladoc/api/attribute.vala b/src/libvaladoc/api/attribute.vala index 1d31894d3..04fac9b18 100644 --- a/src/libvaladoc/api/attribute.vala +++ b/src/libvaladoc/api/attribute.vala @@ -41,6 +41,18 @@ public class Valadoc.Api.Attribute : Item { this.file = file; } + public AttributeArgument? get_argument (string name) { + if (args != null) { + foreach (AttributeArgument arg in args) { + if (arg.name == name) { + return arg; + } + } + } + + return null; + } + public AttributeArgument add_boolean (string name, bool value, void* data = null) { AttributeArgument arg = new AttributeArgument.boolean (this, file, name, value, data); args.add (arg); diff --git a/src/libvaladoc/api/attributeargument.vala b/src/libvaladoc/api/attributeargument.vala index a15fb3d23..7bcd0c6d8 100644 --- a/src/libvaladoc/api/attributeargument.vala +++ b/src/libvaladoc/api/attributeargument.vala @@ -127,14 +127,8 @@ public class Valadoc.Api.AttributeArgument : Item { SignatureBuilder builder = new SignatureBuilder (); builder.append_attribute (name); - builder.append_attribute ("="); - - if (argument_type == Type.STRING) { - builder.append_literal ("\"" + value + "\""); - } else { - builder.append_literal (value); - } + builder.append_literal (value); return builder.get (); } diff --git a/src/libvaladoc/api/package.vala b/src/libvaladoc/api/package.vala index 6656b4810..85be9bd83 100755 --- a/src/libvaladoc/api/package.vala +++ b/src/libvaladoc/api/package.vala @@ -25,6 +25,7 @@ using Valadoc.Content; using Valadoc.Importer; public class Valadoc.Api.Package : Node { + /** * Specifies whether this package is a dependency */ @@ -79,6 +80,51 @@ public class Valadoc.Api.Package : Node { this.parent = null; } + // + private HashMap> deprecated; + + internal void register_deprecated_symbol (Symbol symbol, string? version) { + if (deprecated == null) { + // some libgee-versions do not like nullable strings + + EqualFunc str_eq0 = (a, b) => { + if (a == null && b == null) { + return true; + } else if (a == null || b == null) { + return false; + } + + return a == b; + }; + + HashFunc str_hash0 = (a) => { + if (a == null) { + return 0; + } + + return a.hash (); + }; + + deprecated = new HashMap> (str_hash0, str_eq0); + } + + ArrayList list = deprecated.get (version); + if (list == null) { + list = new ArrayList (); + deprecated.set (version, list); + } + + list.add (symbol); + } + + public Map> get_deprecated_symbols () { + if (deprecated == null) { + return Map>.empty> (); + } + + return deprecated; + } + /** * {@inheritDoc} */ diff --git a/src/libvaladoc/api/symbol.vala b/src/libvaladoc/api/symbol.vala index 330992153..54f887d6f 100755 --- a/src/libvaladoc/api/symbol.vala +++ b/src/libvaladoc/api/symbol.vala @@ -29,6 +29,12 @@ using Gee; public abstract class Valadoc.Api.Symbol : Node { private ArrayList attributes; + public bool is_deprecated { + default = false; + private set; + get; + } + public Symbol (Node parent, SourceFile file, string? name, SymbolAccessibility accessibility, void* data) { base (parent, file, name, data); @@ -40,6 +46,15 @@ public abstract class Valadoc.Api.Symbol : Node { attributes = new ArrayList (); } + // register deprecated symbols: + if (att.name == "Deprecated") { + AttributeArgument? version = att.get_argument ("version"); + string? version_str = (version == null)? null : version.get_value_as_string (); + + package.register_deprecated_symbol (this, version_str); + is_deprecated = true; + } + attributes.add (att); } @@ -51,6 +66,18 @@ public abstract class Valadoc.Api.Symbol : Node { } } + public Attribute? get_attribute (string name) { + if (attributes != null) { + foreach (Attribute att in attributes) { + if (att.name == name) { + return att; + } + } + } + + return null; + } + /** * {@inheritDoc} */ diff --git a/src/libvaladoc/html/basicdoclet.vala b/src/libvaladoc/html/basicdoclet.vala index c8622787c..f624bf52c 100755 --- a/src/libvaladoc/html/basicdoclet.vala +++ b/src/libvaladoc/html/basicdoclet.vala @@ -94,6 +94,7 @@ public abstract class Valadoc.Html.BasicDoclet : Api.Visitor, Doclet { private const string css_style_navigation = "site_navigation"; private const string css_style_content = "site_content"; private const string css_style_body = "site_body"; + private const string css_deprecated = "deprecated"; public virtual void process (Settings settings, Api.Tree tree, ErrorReporter reporter) { this.settings = settings; @@ -126,15 +127,31 @@ public abstract class Valadoc.Html.BasicDoclet : Api.Visitor, Doclet { - protected void write_navi_entry_html_template (string style, string content) { + protected void write_navi_entry_html_template (string style, string content, bool is_deprecated) { writer.start_tag ("li", {"class", style}); - writer.text (content); + + if (is_deprecated) { + writer.start_tag ("span", {"class", css_deprecated}); + writer.text (content); + writer.end_tag ("span"); + } else { + writer.text (content); + } + writer.end_tag ("li"); } - protected void write_navi_entry_html_template_with_link (string style, string link, string content) { + protected void write_navi_entry_html_template_with_link (string style, string link, string content, bool is_deprecated) { writer.start_tag ("li", {"class", style}); - writer.link (link, content); + + if (is_deprecated) { + writer.start_tag ("span", {"class", css_deprecated}); + writer.link (link, content); + writer.end_tag ("span"); + } else { + writer.link (link, content); + } + writer.end_tag ("li"); } @@ -149,10 +166,12 @@ public abstract class Valadoc.Html.BasicDoclet : Api.Visitor, Doclet { name = (tmp == null)? "Global Namespace" : tmp; } + bool is_deprecated = element is Symbol && ((Symbol) element).is_deprecated; + if (link == true) { - this.write_navi_entry_html_template_with_link (style, this.get_link (element, pos), name); + this.write_navi_entry_html_template_with_link (style, this.get_link (element, pos), name, is_deprecated); } else { - this.write_navi_entry_html_template (style, name); + this.write_navi_entry_html_template (style, name, is_deprecated); } } @@ -370,14 +389,54 @@ public abstract class Valadoc.Html.BasicDoclet : Api.Visitor, Doclet { private void write_documentation (Api.Node element , Api.Node? pos) { Content.Comment? doctree = element.documentation; - if (doctree == null) { + Attribute? deprecated = (element is Symbol)? ((Symbol) element).get_attribute ("Deprecated") : null; + + // avoid empty divs + if (doctree == null && deprecated == null) { return; } + writer.start_tag ("div", {"class", css_description}); - _renderer.set_container (pos); - _renderer.render (doctree); + // deprecation warning: + if (deprecated != null) { + AttributeArgument? replacement = deprecated.get_argument ("replacement"); + AttributeArgument? version = deprecated.get_argument ("version"); + + writer.start_tag ("p"); + writer.start_tag ("b"); + writer.text ("Warning:"); + writer.end_tag ("b"); + writer.text (" %s is deprecated".printf (element.name)); + + if (version != null) { + writer.text (" since %s".printf (version.get_value_as_string ())); + } + + writer.text ("."); + + if (replacement != null) { + string replacement_name = replacement.get_value_as_string (); + Api.Node? replacement_node = tree.search_symbol_str (pos, replacement_name.substring (1, replacement_name.length - 2)); + + writer.text (" Use "); + if (replacement_node == null) { + writer.text (replacement_name); + } else { + string css = cssresolver.resolve (replacement_node); + writer.link (get_link (replacement_node, pos), replacement_node.get_full_name (), css); + } + writer.text ("."); + } + + writer.end_tag ("p"); + } + + if (doctree != null) { + _renderer.set_container (pos); + _renderer.render (doctree); + } writer.end_tag ("div"); } @@ -655,12 +714,24 @@ public abstract class Valadoc.Html.BasicDoclet : Api.Visitor, Doclet { foreach (Api.Node child in children) { writer.start_tag ("li", {"class", cssresolver.resolve (child)}); if (is_internal_node (child)) { - writer.link (get_link (child, container), child.name); + if (child is Symbol && ((Symbol) child).is_deprecated) { + writer.start_tag ("span", {"class", css_deprecated}); + writer.link (get_link (child, container), child.name); + writer.end_tag ("span"); + } else { + writer.link (get_link (child, container), child.name); + } writer.text (" - "); write_brief_description (child, container); } else { writer.start_tag ("span", {"class", css_leaf_code_definition}); - write_signature (child, container); + if (child is Symbol && ((Symbol) child).is_deprecated) { + writer.start_tag ("span", {"class", css_deprecated}); + write_signature (child, container); + writer.end_tag ("span"); + } else { + write_signature (child, container); + } writer.end_tag ("span"); writer.start_tag ("div", {"class", css_leaf_brief_description});