GNOME.org
 

[valadoc] libvaladoc/html: Mark deprecated symbols

commit bc2b84e6854c7cf7e935a42dbfd6aa3e867a38f2
Author: Florian Brosch <flo brosch gmail com>
Date:   Fri Aug 12 02:32:51 2011 +0200

    libvaladoc/html: Mark deprecated symbols

 icons/devhelpstyle.css                    |    3 +
 icons/style.css                           |    3 +
 icons/wikistyle.css                       |    3 +
 src/libvaladoc/api/attribute.vala         |   12 ++++
 src/libvaladoc/api/attributeargument.vala |    8 +--
 src/libvaladoc/api/package.vala           |   46 ++++++++++++++
 src/libvaladoc/api/symbol.vala            |   27 ++++++++
 src/libvaladoc/html/basicdoclet.vala      |   93 +++++++++++++++++++++++++----
 8 files changed, 177 insertions(+), 18 deletions(-)
---
diff --git a/icons/devhelpstyle.css b/icons/devhelpstyle.css
index 19392d1..fa181e2 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 0456417..e556fbd 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 9c878ce..56ca6bc 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 1d31894..04fac9b 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 a15fb3d..7bcd0c6 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 6656b48..85be9bd 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;
 	}
 
+	// <version, symbols>
+	private HashMap<string?, ArrayList<Symbol>> deprecated;
+
+	internal void register_deprecated_symbol (Symbol symbol, string? version) {
+		if (deprecated == null) {
+			// some libgee-versions do not like nullable strings
+
+			EqualFunc<string?> str_eq0 = (a, b) => { 
+				if (a == null && b == null) {
+					return true;
+				} else if (a == null || b == null) {
+					return false;
+				}
+
+				return a == b;
+			};
+
+			HashFunc<string?> str_hash0 = (a) => {
+				if (a == null) {
+					return 0;
+				}
+
+				return a.hash ();
+			};
+
+			deprecated = new HashMap<string?, ArrayList<Symbol>> (str_hash0, str_eq0);
+		}
+
+		ArrayList<Symbol> list = deprecated.get (version);
+		if (list == null) {
+			list = new ArrayList<Symbol> ();
+			deprecated.set (version, list);
+		}
+
+		list.add (symbol);
+	}
+
+	public Map<string?, Collection<Symbol>> get_deprecated_symbols () {
+		if (deprecated == null) {
+			return Map<string?, Collection<Symbol>>.empty<string?, Collection<Symbol>> ();
+		}
+
+		return deprecated;
+	}
+
 	/**
 	 * { inheritDoc}
 	 */
diff --git a/src/libvaladoc/api/symbol.vala b/src/libvaladoc/api/symbol.vala
index 3309921..54f887d 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<Attribute> 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<Attribute> ();
 		}
 
+		// 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 c862278..f624bf5 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});
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]