Merge valadoc 0.36.0

Consider valadoc a part of vala's toolchain and therefore let it live in
the main repository.

With this merge there is no need to maintain multiple driver sources since
only one is required from now on.

There is no dependency on gee-0.8 and vala's internal gee copy has made to
be sufficient.

The libvaladoc library will be suffixed with vala's version suffix too.
Besides this renaming the rest of the valadoc file layout is kept the same.

https://bugzilla.gnome.org/show_bug.cgi?id=782782

9 files changed, 1017 insertions, 0 deletions

diff --git a/libvaladoc/taglets/tagletdeprecated.vala b/libvaladoc/taglets/tagletdeprecated.vala
new file mode 100644
index 000000000..5911ef844
--- /dev/null
+++ b/libvaladoc/taglets/tagletdeprecated.vala
@@ -0,0 +1,60 @@
+/* tagletdeprecated.vala
+ *
+ * Copyright (C) 2008-2009 Didier Villevalois
+ * Copyright (C) 2008-2012 Florian Brosch
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301  USA
+ *
+ * Author:
+ * 	Didier 'Ptitjes Villevalois <ptitjes@free.fr>
+ */
+
+
+using Valadoc.Content;
+
+public class Valadoc.Taglets.Deprecated : BlockContent, Taglet, Block {
+	public Rule? get_parser_rule (Rule run_rule) {
+		return run_rule;
+	}
+
+	public override void check (Api.Tree api_root, Api.Node container, string file_path,
+								ErrorReporter reporter, Settings settings)
+	{
+		base.check (api_root, container, file_path, reporter, settings);
+		reporter.simple_warning ("%s: %s: @deprecated".printf (file_path, container.get_full_name ()),
+								 "@deprecated is deprecated. Use [Version (deprecated = true)]");
+	}
+
+	public override void accept (ContentVisitor visitor) {
+		visitor.visit_taglet (this);
+	}
+
+	public override bool is_empty () {
+		return false;
+	}
+
+	public override ContentElement copy (ContentElement? new_parent = null) {
+		Deprecated deprecated = new Deprecated ();
+		deprecated.parent = new_parent;
+
+		foreach (Block element in content) {
+			Block copy = element.copy (deprecated) as Block;
+			deprecated.content.add (copy);
+		}
+
+		return deprecated;
+	}
+}
+
diff --git a/libvaladoc/taglets/tagletinheritdoc.vala b/libvaladoc/taglets/tagletinheritdoc.vala
new file mode 100644
index 000000000..5ce4a8c31
--- /dev/null
+++ b/libvaladoc/taglets/tagletinheritdoc.vala
@@ -0,0 +1,232 @@
+/* tagletinheritdoc.vala
+ *
+ * Copyright (C) 2008-2009 Didier Villevalois
+ * Copyright (C) 2008-2012 Florian Brosch
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301  USA
+ *
+ * Author:
+ * 	Didier 'Ptitjes Villevalois <ptitjes@free.fr>
+ */
+
+
+using Valadoc.Content;
+
+public class Valadoc.Taglets.InheritDoc : InlineTaglet {
+	private Taglet? parent_taglet = null;
+
+	public Api.Node? inherited {
+		private set;
+		get;
+	}
+
+
+	public override Rule? get_parser_rule (Rule run_rule) {
+		return null;
+	}
+
+	private Taglet? find_parent_taglet () {
+		if (_inherited == null || _inherited.documentation == null) {
+			return null;
+		}
+
+		ContentElement pos;
+		for (pos = this.parent; pos != null && pos is Taglet == false; pos = pos.parent);
+		if (pos is Taglet) {
+			return (Taglet) pos;
+		}
+
+		return null;
+	}
+
+	public override void check (Api.Tree api_root, Api.Node container, string file_path,
+								ErrorReporter reporter, Settings settings)
+	{
+		// TODO Check that the container is an override of an abstract symbol
+		// Also retrieve that abstract symbol _inherited
+
+		if (container is Api.Method) {
+			_inherited = ((Api.Method) container).base_method;
+		} else if (container is Api.Property) {
+			_inherited = ((Api.Property) container).base_property;
+		} else if (container is Api.Class && ((Api.Class) container).base_type != null) {
+			_inherited = (Api.Node) ((Api.Class) container).base_type.data_type;
+		} else if (container is Api.Struct && ((Api.Struct) container).base_type != null) {
+			_inherited = (Api.Node) ((Api.Struct) container).base_type.data_type;
+		}
+
+		parent_taglet = find_parent_taglet ();
+		if (parent_taglet == null && _inherited != null) {
+			api_root.register_inheritdoc (container, this);
+		}
+
+
+		// TODO report error if inherited is null
+
+		// TODO postpone check after complete parse of the api tree comments
+		// And reenable that check
+		//base.check (api_root, container, reporter);
+	}
+
+	private Run[]? split_run (Inline? separator) {
+		if (separator == null) {
+			return null;
+		}
+
+		ContentElement parent = separator.parent;
+		Vala.List<Inline> parent_content = null;
+
+		if (parent is Run && ((Run) parent).style == Run.Style.NONE) {
+			parent_content = ((Run) parent).content;
+		} else if (parent is Paragraph) {
+			parent_content = ((Paragraph) parent).content;
+		}
+
+		if (parent_content != null) {
+			Run right_run = new Run (Run.Style.NONE);
+			Run left_run = new Run (Run.Style.NONE);
+			bool separated = false;
+
+			foreach (var current in parent_content) {
+				if (current == separator) {
+					separated = true;
+				} else if (separated) {
+					right_run.content.add (current);
+					current.parent = right_run;
+				} else {
+					left_run.content.add (current);
+					current.parent = left_run;
+				}
+			}
+
+			return { left_run, right_run };
+		}
+
+		return null;
+	}
+
+	internal void transform (Api.Tree api_root, Api.Node container, string file_path,
+							 ErrorReporter reporter, Settings settings)
+	{
+		ContentElement separator = this;
+		Run right_run = null;
+		Run left_run = null;
+		Run[]? parts;
+
+		while ((parts = split_run (separator as Inline)) != null) {
+			if (left_run != null) {
+				parts[0].content.add (left_run);
+				left_run.parent = parts[0];
+			}
+
+			if (right_run != null) {
+				parts[1].content.insert (0, right_run);
+				right_run.parent = parts[1];
+			}
+
+			separator = separator.parent;
+			right_run = parts[1];
+			left_run = parts[0];
+		}
+
+		if (separator is Paragraph == false || separator.parent is Comment == false) {
+			reporter.simple_error ("%s: %s: @inheritDoc".printf (file_path, container.get_full_name ()),
+								   "Parent documentation can't be copied to this location.");
+			return ;
+		}
+
+		Comment comment = separator.parent as Comment;
+		assert (comment != null);
+
+		int insert_pos = comment.content.index_of ((Paragraph) separator);
+		int start_pos = insert_pos;
+		assert (insert_pos >= 0);
+
+		foreach (Block block in _inherited.documentation.content) {
+			comment.content.insert (insert_pos, (Block) block.copy (comment));
+			insert_pos++;
+		}
+
+		if (right_run != null) {
+			if (comment.content[insert_pos - 1] is Paragraph) {
+				((Paragraph) comment.content[insert_pos - 1]).content.add (right_run);
+				right_run.parent = comment.content[insert_pos - 1];
+			} else {
+				Paragraph p = new Paragraph ();
+				p.content.add (right_run);
+				right_run.parent = p;
+				p.parent = comment;
+				comment.content.insert (insert_pos, p);
+			}
+		}
+
+		if (left_run != null) {
+			if (comment.content[start_pos] is Paragraph) {
+				((Paragraph) comment.content[start_pos]).content.insert (0, left_run);
+				left_run.parent = comment.content[start_pos];
+			} else {
+				Paragraph p = new Paragraph ();
+				p.content.add (left_run);
+				left_run.parent = p;
+				p.parent = comment;
+				comment.content.insert (start_pos, p);
+			}
+		}
+
+		comment.content.remove ((Paragraph) separator);
+	}
+
+	private Run content_copy (Vala.List<ContentElement>? content) {
+		Run run = new Run (Run.Style.NONE);
+		run.parent = this;
+
+		if (content != null) {
+			foreach (ContentElement item in content) {
+				run.content.add (item.copy (this) as Inline);
+			}
+		}
+
+		return run;
+	}
+
+	public override ContentElement produce_content () {
+		if (_inherited != null && _inherited.documentation != null && parent_taglet != null) {
+			Vala.List<Taglet> parent_taglets = _inherited.documentation.find_taglets (null, parent_taglet.get_type ());
+			foreach (Taglet parent in parent_taglets) {
+				// we only care about the first match:
+				if (parent.inheritable (parent_taglet)) {
+					return content_copy (parent.get_inheritable_documentation ());
+				}
+			}
+		}
+		return new Text ("");
+	}
+
+	public override bool is_empty () {
+		return false;
+	}
+
+	public override ContentElement copy (ContentElement? new_parent = null) {
+		InheritDoc doc = new InheritDoc ();
+		doc.parent = new_parent;
+
+		doc.settings = settings;
+		doc.locator = locator;
+
+		doc._inherited = _inherited;
+
+		return doc;
+	}
+}
diff --git a/libvaladoc/taglets/tagletinit.vala b/libvaladoc/taglets/tagletinit.vala
new file mode 100644
index 000000000..7e88126aa
--- /dev/null
+++ b/libvaladoc/taglets/tagletinit.vala
@@ -0,0 +1,35 @@
+/* tagletinit.vala
+ *
+ * Copyright (C) 2008-2009 Florian Brosch
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301  USA
+ *
+ * Author:
+ * 	Florian Brosch <flo.brosch@gmail.com>
+ */
+
+
+namespace Valadoc.Taglets {
+	public void init (ModuleLoader loader) {
+		loader.register_taglet ("see", typeof (Valadoc.Taglets.See));
+		loader.register_taglet ("since", typeof (Valadoc.Taglets.Since));
+		loader.register_taglet ("link", typeof (Valadoc.Taglets.Link));
+		loader.register_taglet ("throws", typeof (Valadoc.Taglets.Throws));
+		loader.register_taglet ("return", typeof (Valadoc.Taglets.Return));
+		loader.register_taglet ("param", typeof (Valadoc.Taglets.Param));
+		loader.register_taglet ("deprecated", typeof (Valadoc.Taglets.Deprecated));
+		loader.register_taglet ("inheritDoc", typeof (Valadoc.Taglets.InheritDoc));
+	}
+}
diff --git a/libvaladoc/taglets/tagletlink.vala b/libvaladoc/taglets/tagletlink.vala
new file mode 100644
index 000000000..799bec6e0
--- /dev/null
+++ b/libvaladoc/taglets/tagletlink.vala
@@ -0,0 +1,185 @@
+/* taglet.vala
+ *
+ * Copyright (C) 2008-2009 Didier Villevalois
+ * Copyright (C) 2008-2014 Florian Brosch
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301  USA
+ *
+ * Author:
+ * 	Didier 'Ptitjes Villevalois <ptitjes@free.fr>
+ */
+
+
+using Valadoc.Content;
+
+public class Valadoc.Taglets.Link : InlineTaglet {
+	public string symbol_name { internal set; get; }
+
+	/**
+	 * Accept leading 's', e.g. #Widgets
+	 */
+	public bool c_accept_plural { internal set; get; }
+
+	/**
+	 * True if symbol_name could only be resolved after removing 's'
+	 *
+	 * E.g. true or #Widgets, false for #Widget
+	 */
+	public bool c_is_plural { private set; get; }
+
+
+	private enum SymbolContext {
+		NORMAL,
+		FINISH,
+		TYPE
+	}
+
+	private SymbolContext _context = SymbolContext.NORMAL;
+	private Api.Node _symbol;
+
+	public override Rule? get_parser_rule (Rule run_rule) {
+		return Rule.seq ({
+			Rule.option ({ Rule.many ({ TokenType.SPACE }) }),
+			TokenType.any_word ().action ((token) => { symbol_name = token.to_string (); }),
+			Rule.option ({
+				Rule.many ({
+					Rule.one_of ({
+						TokenType.any_word ().action ((token) => { symbol_name += token.to_string (); }),
+						TokenType.MINUS.action ((token => { symbol_name += token.to_string (); }))
+					})
+				})
+			})
+		});
+	}
+
+	public override void check (Api.Tree api_root, Api.Node container, string file_path,
+								ErrorReporter reporter, Settings settings) {
+
+		if (symbol_name.has_prefix ("c::")) {
+			_symbol_name = _symbol_name.substring (3);
+			string? singular_symbol_name = (c_accept_plural && _symbol_name.has_suffix ("s"))
+				? symbol_name.substring (0, _symbol_name.length - 1)
+				: null;
+
+			_symbol = api_root.search_symbol_cstr (container, symbol_name);
+			if (_symbol == null && singular_symbol_name != null) {
+				_symbol = api_root.search_symbol_cstr (container, singular_symbol_name);
+				c_is_plural = true;
+			}
+			_context = SymbolContext.NORMAL;
+
+			if (_symbol == null && _symbol_name.has_suffix ("_finish")) {
+				string tmp = _symbol_name.substring (0, _symbol_name.length - 7);
+
+				_symbol = api_root.search_symbol_cstr (container, tmp + "_async") as Api.Method;
+				if (_symbol != null && ((Api.Method) _symbol).is_yields) {
+					_context = SymbolContext.FINISH;
+				} else {
+					_symbol = api_root.search_symbol_cstr (container, tmp) as Api.Method;
+					if (_symbol != null && ((Api.Method) _symbol).is_yields) {
+						_context = SymbolContext.FINISH;
+					} else {
+						_symbol = null;
+					}
+				}
+			}
+
+			if (_symbol == null) {
+				_symbol = api_root.search_symbol_type_cstr (symbol_name);
+				if (_symbol == null && singular_symbol_name != null) {
+					_symbol = api_root.search_symbol_type_cstr (singular_symbol_name);
+					c_is_plural = true;
+				}
+				if (_symbol != null) {
+					_context = SymbolContext.TYPE;
+				}
+			}
+
+			if (_symbol != null) {
+				symbol_name = _symbol.name;
+			}
+		} else {
+			_symbol = api_root.search_symbol_str (container, symbol_name);
+		}
+
+		if (_symbol == null && symbol_name != "main") {
+			string node_segment = (container is Api.Package)? "" : container.get_full_name () + ": ";
+			reporter.simple_warning ("%s: %s@link".printf (file_path, node_segment),
+									 "`%s' does not exist", symbol_name);
+		}
+
+		base.check (api_root, container, file_path, reporter, settings);
+	}
+
+	public override ContentElement produce_content () {
+		var link = new Content.SymbolLink ();
+		link.symbol = _symbol;
+		link.given_symbol_name = symbol_name;
+
+		Content.Inline content;
+		switch (_context) {
+		case SymbolContext.FINISH:
+			link.given_symbol_name += ".end";
+			content = link;
+			break;
+
+		case SymbolContext.TYPE:
+			Run run = new Content.Run (Run.Style.MONOSPACED);
+			content = run;
+
+			Content.Run keyword = new Content.Run (Run.Style.LANG_KEYWORD);
+			keyword.content.add (new Content.Text ("typeof"));
+			run.content.add (keyword);
+
+			run.content.add (new Content.Text (" ("));
+			run.content.add (link);
+			run.content.add (new Content.Text (")"));
+			break;
+
+		default:
+			content = link;
+			break;
+		}
+
+		if (c_is_plural == true) {
+			Run run = new Content.Run (Run.Style.NONE);
+			run.content.add (content);
+			run.content.add (new Content.Text ("s"));
+			return run;
+		}
+
+		return content;
+	}
+
+	public override bool is_empty () {
+		return false;
+	}
+
+	public override ContentElement copy (ContentElement? new_parent = null) {
+		Link link = new Link ();
+		link.parent = new_parent;
+
+		link.settings = settings;
+		link.locator = locator;
+
+		link.symbol_name = symbol_name;
+		link.c_accept_plural = c_accept_plural;
+		link.c_is_plural = c_is_plural;
+		link._context = _context;
+		link._symbol = _symbol;
+
+		return link;
+	}
+}
diff --git a/libvaladoc/taglets/tagletparam.vala b/libvaladoc/taglets/tagletparam.vala
new file mode 100644
index 000000000..274669100
--- /dev/null
+++ b/libvaladoc/taglets/tagletparam.vala
@@ -0,0 +1,165 @@
+/* taglet.vala
+ *
+ * Copyright (C) 2008-2009 Didier Villevalois
+ * Copyright (C) 2008-2012 Florian Brosch
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301  USA
+ *
+ * Author:
+ * 	Didier 'Ptitjes Villevalois <ptitjes@free.fr>
+ */
+
+
+using Valadoc.Content;
+
+public class Valadoc.Taglets.Param : BlockContent, Taglet, Block {
+	public string parameter_name { internal set; get; }
+
+	public weak Api.Symbol? parameter { private set; get; }
+
+	public int position { private set; get; default = -1; }
+
+	public bool is_c_self_param { internal set; get; }
+
+	public bool is_this { private set; get; }
+
+
+	public Rule? get_parser_rule (Rule run_rule) {
+		return Rule.seq ({
+			Rule.option ({ Rule.many ({ TokenType.SPACE }) }),
+			TokenType.any_word ().action ((token) => { parameter_name = token.to_string (); }),
+			run_rule
+		});
+	}
+
+	public override void check (Api.Tree api_root, Api.Node container, string file_path,
+								ErrorReporter reporter, Settings settings)
+	{
+		// Check for the existence of such a parameter
+		unowned string? implicit_return_array_length = null;
+		bool has_instance = has_instance (container);
+		bool is_implicit = false;
+		this.parameter = null;
+
+		if (container is Api.Callable) {
+			implicit_return_array_length = ((Api.Callable) container).implicit_array_length_cparameter_name;
+		} else {
+			reporter.simple_warning ("%s: %s: @param".printf (file_path, container.get_full_name ()),
+									 "@param used outside method/delegate/signal context");
+			base.check (api_root, container, file_path, reporter, settings);
+			return ;
+		}
+
+		if (is_c_self_param == true && has_instance) {
+			this.parameter_name = "this";
+			this.is_this = true;
+			this.position = 0;
+		} else if (parameter_name == "...") {
+			Vala.List<Api.Node> params = container.get_children_by_type (Api.NodeType.FORMAL_PARAMETER, false);
+			foreach (Api.Node param in params) {
+				if (((Api.FormalParameter) param).ellipsis) {
+					this.parameter = (Api.Symbol) param;
+					this.position = (has_instance)? params.size : params.size - 1;
+					break;
+				}
+			}
+		} else {
+			Vala.List<Api.Node> params = container.get_children_by_types ({Api.NodeType.FORMAL_PARAMETER,
+																		  Api.NodeType.TYPE_PARAMETER},
+																		 false);
+			int pos = (has_instance)? 1 : 0;
+
+			foreach (Api.Node param in params) {
+				if (param.name == parameter_name) {
+					this.parameter = (Api.Symbol) param;
+					this.position = pos;
+					break;
+				}
+
+				Api.FormalParameter formalparam = param as Api.FormalParameter;
+				if (formalparam != null && (formalparam.implicit_array_length_cparameter_name == parameter_name
+					|| formalparam.implicit_closure_cparameter_name == parameter_name
+					|| formalparam.implicit_destroy_cparameter_name == parameter_name))
+				{
+					is_implicit = true;
+					break;
+				}
+
+				pos++;
+			}
+
+			if (this.parameter == null
+				&& (parameter_name == "error"
+				&& container.has_children ({Api.NodeType.ERROR_DOMAIN, Api.NodeType.CLASS})
+			   || parameter_name == implicit_return_array_length))
+			{
+				is_implicit = true;
+			}
+		}
+
+		if (this.parameter == null) {
+			if (is_implicit) {
+				reporter.simple_note ("%s: %s: @param".printf (file_path, container.get_full_name ()),
+									  "Implicit parameter `%s' exposed in documentation", parameter_name);
+			} else if (!is_c_self_param) {
+				reporter.simple_warning ("%s: %s: @param".printf (file_path, container.get_full_name ()),
+										 "Unknown parameter `%s'", parameter_name);
+			}
+		}
+
+		base.check (api_root, container, file_path, reporter, settings);
+	}
+
+	private bool has_instance (Api.Item element) {
+		if (element is Api.Method) {
+			return !((Api.Method) element).is_static;
+		}
+
+		return false;
+	}
+
+	public override void accept (ContentVisitor visitor) {
+		visitor.visit_taglet (this);
+	}
+
+	public Vala.List<ContentElement>? get_inheritable_documentation () {
+		return content;
+	}
+
+	public bool inheritable (Taglet taglet) {
+		if (taglet is Taglets.Param == false) {
+			return false;
+		}
+
+		Taglets.Param t = (Taglets.Param) taglet;
+		return (parameter == t.parameter || parameter_name == t.parameter_name);
+	}
+
+	public override ContentElement copy (ContentElement? new_parent = null) {
+		Param param = new Param ();
+		param.parent = new_parent;
+
+		param.parameter_name = parameter_name;
+		param.parameter = parameter;
+		param.position = position;
+
+		foreach (Block element in content) {
+			Block copy = element.copy (param) as Block;
+			param.content.add (copy);
+		}
+
+		return param;
+	}
+}
diff --git a/libvaladoc/taglets/tagletreturn.vala b/libvaladoc/taglets/tagletreturn.vala
new file mode 100644
index 000000000..691a4a31f
--- /dev/null
+++ b/libvaladoc/taglets/tagletreturn.vala
@@ -0,0 +1,78 @@
+/* taglet.vala
+ *
+ * Copyright (C) 2008-2009 Didier Villevalois
+ * Copyright (C) 2008-2012 Florian Brosch
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301  USA
+ *
+ * Author:
+ * 	Didier 'Ptitjes Villevalois <ptitjes@free.fr>
+ */
+
+
+using Valadoc.Content;
+
+public class Valadoc.Taglets.Return : BlockContent, Taglet, Block {
+	public Rule? get_parser_rule (Rule run_rule) {
+		return run_rule;
+	}
+
+	public override void check (Api.Tree api_root, Api.Node container, string file_path,
+								ErrorReporter reporter, Settings settings) {
+		Api.TypeReference? type_ref = null;
+		bool creation_method = false;
+
+		if (container is Api.Method) {
+			creation_method = ((Api.Method) container).is_constructor;
+			type_ref = ((Api.Method) container).return_type;
+		} else if (container is Api.Callable) {
+			type_ref = ((Api.Callable) container).return_type;
+		} else {
+			reporter.simple_warning ("%s: %s: @return".printf (file_path, container.get_full_name ()),
+									 "@return used outside method/delegate/signal context");
+		}
+
+		if (type_ref != null && type_ref.data_type == null && !creation_method) {
+			reporter.simple_warning ("%s: %s: @return".printf (file_path, container.get_full_name ()),
+									 "Return description declared for void function");
+		}
+
+		base.check (api_root, container, file_path, reporter, settings);
+	}
+
+	public override void accept (ContentVisitor visitor) {
+		visitor.visit_taglet (this);
+	}
+
+	public Vala.List<ContentElement>? get_inheritable_documentation () {
+		return content;
+	}
+
+	public bool inheritable (Taglet taglet) {
+		return taglet is Taglets.Return;
+	}
+
+	public override ContentElement copy (ContentElement? new_parent = null) {
+		Return ret = new Return ();
+		ret.parent = new_parent;
+
+		foreach (Block element in content) {
+			Block copy = element.copy (ret) as Block;
+			ret.content.add (copy);
+		}
+
+		return ret;
+	}
+}
diff --git a/libvaladoc/taglets/tagletsee.vala b/libvaladoc/taglets/tagletsee.vala
new file mode 100644
index 000000000..f509443e5
--- /dev/null
+++ b/libvaladoc/taglets/tagletsee.vala
@@ -0,0 +1,76 @@
+/* tagletsee.vala
+ *
+ * Copyright (C) 2008-2009 Didier Villevalois
+ * Copyright (C) 2008-2012 Florian Brosch
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301  USA
+ *
+ * Author:
+ * 	Didier 'Ptitjes Villevalois <ptitjes@free.fr>
+ */
+
+
+using Valadoc.Content;
+
+public class Valadoc.Taglets.See : ContentElement, Taglet, Block {
+	public string symbol_name { private set; get; }
+	public Api.Node symbol { private set; get; }
+
+	public Rule? get_parser_rule (Rule run_rule) {
+		Rule optional_spaces = Rule.option ({ Rule.many ({ TokenType.SPACE }) });
+
+		return Rule.seq ({
+			optional_spaces,
+			TokenType.any_word ().action ((token) => { symbol_name = token.to_string (); }),
+			optional_spaces
+		});
+	}
+
+	public override void check (Api.Tree api_root, Api.Node container, string file_path,
+								ErrorReporter reporter, Settings settings) {
+		if (symbol_name.has_prefix ("c::")) {
+			symbol_name = symbol_name.substring (3);
+			symbol = api_root.search_symbol_cstr (container, symbol_name);
+			if (symbol != null) {
+				symbol_name = _symbol.name;
+			}
+		} else {
+			symbol = api_root.search_symbol_str (container, symbol_name);
+		}
+
+		if (symbol == null) {
+			// TODO use ContentElement's source reference
+			reporter.simple_warning ("%s: %s: @see".printf (file_path, container.get_full_name ()),
+									 "`%s' does not exist", symbol_name);
+		}
+	}
+
+	public override void accept (ContentVisitor visitor) {
+		visitor.visit_taglet (this);
+	}
+
+	public override bool is_empty () {
+		return false;
+	}
+
+	public override ContentElement copy (ContentElement? new_parent = null) {
+		See see = new See ();
+		see.parent = new_parent;
+
+		see.symbol_name = symbol_name;
+		see.symbol = symbol;
+
+		return see;
+	}}
diff --git a/libvaladoc/taglets/tagletsince.vala b/libvaladoc/taglets/tagletsince.vala
new file mode 100644
index 000000000..124474204
--- /dev/null
+++ b/libvaladoc/taglets/tagletsince.vala
@@ -0,0 +1,62 @@
+/* tagletsince.vala
+ *
+ * Copyright (C) 2008-2009 Didier Villevalois
+ * Copyright (C) 2008-2012 Florian Brosch
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301  USA
+ *
+ * Author:
+ * 	Didier 'Ptitjes Villevalois <ptitjes@free.fr>
+ */
+
+
+using Valadoc.Content;
+
+public class Valadoc.Taglets.Since : ContentElement, Taglet, Block {
+	public string version { get; internal set; }
+
+	public Rule? get_parser_rule (Rule run_rule) {
+		Rule optional_spaces = Rule.option ({ Rule.many ({ TokenType.SPACE }) });
+
+		return Rule.seq ({
+			optional_spaces,
+			TokenType.any_word ().action ((token) => { version = token.to_string (); }),
+			optional_spaces
+		});
+	}
+
+	public override void check (Api.Tree api_root, Api.Node container, string file_path,
+								ErrorReporter reporter, Settings settings)
+	{
+	}
+
+	public override void accept (ContentVisitor visitor) {
+		visitor.visit_taglet (this);
+	}
+
+	public override bool is_empty () {
+		return false;
+	}
+
+	public override ContentElement copy (ContentElement? new_parent = null) {
+		Since since = new Since ();
+		since.parent = new_parent;
+
+		since.version = version;
+
+		return since;
+	}
+}
+
diff --git a/libvaladoc/taglets/tagletthrows.vala b/libvaladoc/taglets/tagletthrows.vala
new file mode 100644
index 000000000..6a945515d
--- /dev/null
+++ b/libvaladoc/taglets/tagletthrows.vala
@@ -0,0 +1,124 @@
+/* tagletthrows.vala
+ *
+ * Copyright (C) 2008-2009 Didier Villevalois
+ * Copyright (C) 2008-2012 Florian Brosch
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301  USA
+ *
+ * Author:
+ * 	Didier 'Ptitjes Villevalois <ptitjes@free.fr>
+ */
+
+
+using Valadoc.Content;
+
+public class Valadoc.Taglets.Throws : BlockContent, Taglet, Block {
+	// TODO: rename
+	public string error_domain_name { private set; get; }
+
+	/**
+	 * Thrown  Error domain or Error code
+	 */
+	// TODO: rename
+	public Api.Node error_domain { private set; get; }
+
+	public Rule? get_parser_rule (Rule run_rule) {
+		return Rule.seq ({
+			Rule.option ({ Rule.many ({ TokenType.SPACE }) }),
+			TokenType.any_word ().action ((token) => { error_domain_name = token.to_string (); }),
+			run_rule
+		});
+	}
+
+	public override void check (Api.Tree api_root, Api.Node container, string file_path,
+								ErrorReporter reporter, Settings settings)
+	{
+		// context check:
+		if (container is Api.Method == false && container is Api.Delegate == false) {
+			reporter.simple_warning ("%s: %s: @throws".printf (file_path, container.get_full_name ()),
+									 "@throws used outside method/delegate context");
+			base.check (api_root, container, file_path, reporter, settings);
+			return ;
+		}
+
+
+		// type check:
+		error_domain = api_root.search_symbol_str (container, error_domain_name);
+		if (error_domain == null) {
+			// TODO use ContentElement's source reference
+			reporter.simple_error ("%s: %s: @throws".printf (file_path, container.get_full_name ()),
+								   "`%s' does not exist", error_domain_name);
+			base.check (api_root, container, file_path, reporter, settings);
+			return ;
+		}
+
+
+		// Check if the method is allowed to throw the given type or error code:
+		Vala.List<Api.Node> exceptions = container.get_children_by_types ({Api.NodeType.ERROR_DOMAIN,
+																		  Api.NodeType.CLASS},
+																		 false);
+		Api.Item expected_error_domain = (error_domain is Api.ErrorCode)
+			? error_domain.parent
+			: error_domain;
+		bool report_warning = true;
+		foreach (Api.Node exception in exceptions) {
+			if (exception == expected_error_domain
+				|| (exception is Api.Class && expected_error_domain is Api.ErrorDomain))
+			{
+				report_warning = false;
+				break;
+			}
+		}
+		if (report_warning) {
+			reporter.simple_warning ("%s: %s: @throws".printf (file_path, container.get_full_name ()),
+									 "`%s' does not exist in exception list", error_domain_name);
+		}
+
+		base.check (api_root, container, file_path, reporter, settings);
+	}
+
+	public override void accept (ContentVisitor visitor) {
+		visitor.visit_taglet (this);
+	}
+
+	public Vala.List<ContentElement>? get_inheritable_documentation () {
+		return content;
+	}
+
+	public bool inheritable (Taglet taglet) {
+		if (taglet is Taglets.Throws == false) {
+			return false;
+		}
+
+		Taglets.Throws t = (Taglets.Throws) taglet;
+		return (error_domain == t.error_domain || error_domain_name == t.error_domain_name);
+	}
+
+	public override ContentElement copy (ContentElement? new_parent = null) {
+		Throws tr = new Throws ();
+		tr.parent = new_parent;
+
+		tr.error_domain_name = error_domain_name;
+		tr.error_domain = error_domain;
+
+		foreach (Block element in content) {
+			Block copy = element.copy (tr) as Block;
+			tr.content.add (copy);
+		}
+
+		return tr;
+	}
+}
+