From: Florian Brosch Date: Mon, 28 Feb 2011 00:50:26 +0000 (+0100) Subject: libvaladoc/api: Add API documentation for Node X-Git-Tag: 0.37.1~3^2~352 X-Git-Url: http://git.ipfire.org/gitweb/?a=commitdiff_plain;h=b1e06fdc88837f014000cf9045504a9a1be13b23;p=thirdparty%2Fvala.git libvaladoc/api: Add API documentation for Node --- diff --git a/src/libvaladoc/api/node.vala b/src/libvaladoc/api/node.vala index d044895bd..0e4b49c8a 100644 --- a/src/libvaladoc/api/node.vala +++ b/src/libvaladoc/api/node.vala @@ -22,6 +22,10 @@ using Gee; + +/** + * Specifies the context of a node. + */ public enum Valadoc.Api.NodeType { CLASS, CONSTANT, @@ -45,11 +49,20 @@ public enum Valadoc.Api.NodeType { TYPE_PARAMETER } +/** + * Represents a node in the api tree. + */ public abstract class Valadoc.Api.Node : Item, Browsable, Documentation, Comparable { protected bool do_document { private set; get; default = false; } + /** + * The name of the node + */ public abstract string? name { owned get; } + /** + * Returns the type of this node + */ public abstract NodeType node_type { get; } private Map per_name_children; @@ -64,10 +77,21 @@ public abstract class Valadoc.Api.Node : Item, Browsable, Documentation, Compara per_type_children = new HashMap> (int_hash, int_equal); } + /** + * Visits this node with the specified Visitor. + * + * @param visitor the visitor to be called while traversing + */ public abstract void accept (Visitor visitor); + /** + * {@inheritDoc} + */ public abstract bool is_browsable (Settings settings); + /** + * The corresponding file name + */ public virtual string? get_filename () { return null; } @@ -84,13 +108,16 @@ public abstract class Valadoc.Api.Node : Item, Browsable, Documentation, Compara Gee.List children = per_type_children.get (child.node_type); if (children == null) { - per_type_children.set (child.node_type, new ArrayList ()); + children = new ArrayList (); + per_type_children.set (child.node_type, children); } - children = per_type_children.get (child.node_type); children.add (child); } + /** + * {@inheritDoc} + */ internal override void resolve_children (Tree root) { var list = per_type_children.get (NodeType.NAMESPACE); if (list != null) { @@ -121,12 +148,18 @@ public abstract class Valadoc.Api.Node : Item, Browsable, Documentation, Compara } } + /** + * {@inheritDoc} + */ internal override void resolve_type_references (Tree root) { foreach (Node node in per_name_children.values) { node.resolve_type_references (root); } } + /** + * {@inheritDoc} + */ internal override void process_comments (Settings settings, DocumentationParser parser) { do_document = true; @@ -137,11 +170,21 @@ public abstract class Valadoc.Api.Node : Item, Browsable, Documentation, Compara } } + /** + * Specifies whether this node has at least one child with the given type + * + * @param type a node type + */ public bool has_children_by_type (NodeType type) { Gee.List all_children = per_type_children.get (type); return all_children != null && !all_children.is_empty; } + /** + * Specifies whether this node has at least one child with the given types + * + * @param type a list of node types + */ public bool has_children (NodeType[] types) { foreach (NodeType type in types) { if (has_children_by_type (type)) { @@ -151,6 +194,12 @@ public abstract class Valadoc.Api.Node : Item, Browsable, Documentation, Compara return false; } + /** + * Returns a list of all children with the given type. + * + * @param type a list of node types + * @param filtered specifies whether nodes which are not browsable should appear in the list + */ public Gee.List get_children_by_type (NodeType type, bool filtered = true) { var children = new ArrayList (); @@ -166,6 +215,12 @@ public abstract class Valadoc.Api.Node : Item, Browsable, Documentation, Compara return children; } + /** + * Returns a list of all children with the given types. + * + * @param type a list of node types + * @param filtered specifies whether nodes which are not browsable should appear in the list + */ public Gee.List get_children_by_types (NodeType[] types, bool filtered = true) { var children = new ArrayList (); @@ -176,6 +231,13 @@ public abstract class Valadoc.Api.Node : Item, Browsable, Documentation, Compara return children; } + /** + * Visits all children of this node with the given type with the specified Visitor. + * + * @param type a node type + * @param visitor the visitor to be called while traversing + * @param filtered specifies whether nodes which are not browsable should appear in the list + */ public void accept_children_by_type (NodeType type, Visitor visitor, bool filtered = true) { Gee.List all_children = per_type_children.get (type); if (all_children != null) { @@ -187,12 +249,24 @@ public abstract class Valadoc.Api.Node : Item, Browsable, Documentation, Compara } } + /** + * Visits all children of this node with the given types with the specified Visitor. + * + * @param type a list of node types + * @param visitor the visitor to be called while traversing + * @param filtered specifies whether nodes which are not browsable should appear in the list + */ public void accept_children (NodeType[] types, Visitor visitor, bool filtered = true) { foreach (NodeType type in types) { accept_children_by_type (type, visitor, filtered); } } + /** + * Visits all children of this node with the specified Visitor. + * + * @param visitor the visitor to be called while traversing + */ public void accept_all_children (Visitor visitor, bool filtered = true) { foreach (Gee.List children in per_type_children.values) { foreach (Node node in children) { @@ -215,6 +289,9 @@ public abstract class Valadoc.Api.Node : Item, Browsable, Documentation, Compara private Package? _package = null; private string _full_name = null; + /** + * The corresponding namespace + */ public Namespace? nspace { get { if (this._nspace == null) { @@ -230,7 +307,9 @@ public abstract class Valadoc.Api.Node : Item, Browsable, Documentation, Compara } } - + /** + * The corresponding package such as a vapi or gir file + */ public Package? package { get { if (this._package == null) { @@ -250,6 +329,9 @@ public abstract class Valadoc.Api.Node : Item, Browsable, Documentation, Compara get; } + /** + * Returns canonicalized absolute name (GLib.FileStream for instance) + */ public string? get_full_name () { if (this._full_name == null) { if (this.name == null) @@ -271,6 +353,9 @@ public abstract class Valadoc.Api.Node : Item, Browsable, Documentation, Compara return this._full_name; } + /** + * A comparison function used to sort nodes in alphabetical order + */ public int compare_to (Node node) { return strcmp (name, node.name); }