From e8edc3e2c8facdce7b3d8c9f99871b07e36bc226 Mon Sep 17 00:00:00 2001
From: Silvio <s1lv10@uol.com.br>
Date: Fri, 16 Oct 2009 12:10:43 -0300
Subject: Comments

---
 taxonomy_node_tree.module | 76 +++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 74 insertions(+), 2 deletions(-)

diff --git a/taxonomy_node_tree.module b/taxonomy_node_tree.module
index fba8a7c..22ed479 100644
--- a/taxonomy_node_tree.module
+++ b/taxonomy_node_tree.module
@@ -14,6 +14,12 @@
  *
  * This function takes a vocabulary id and returns a
  * list of it's parent terms.
+ *
+ * @param $vid
+ *   Taxonomy id.
+ *
+ * @return
+ *   Array with parent terms of the vocabulary
  */
 function taxonomy_node_tree_parents($vid) {
   // Get all terms from a given vocabulary
@@ -36,8 +42,18 @@ function taxonomy_node_tree_parents($vid) {
  * tree with the corresponding association between terms and
  * nodes.
  *
+ * @param $nodes
+ *   Array with node objects.
+ *    
+ * @param $terms 
+ *   Array with term objects.
+ *
+ * @return
+ *  Term tree with nodes at their parent terms.
+ *
  * @TODO: It is assumed that nodes are just associated with
- *        a single term.
+ *        a single term. This could be changed to support
+ *        multiple relationships.
  */
 function taxonomy_node_tree_index($nodes, $terms) {  
   while ($node = db_fetch_object($nodes)) {
@@ -55,6 +71,12 @@ function taxonomy_node_tree_index($nodes, $terms) {
 
 /**
  * Add children relationship for terms present in the tree.
+ *
+ * @param
+ *   Tree with term objects.
+ *
+ * @return
+ *   Term tree with parent/children relation.
  */
 function taxonomy_node_tree_relation($tree) {
   foreach ($tree as $term) {
@@ -69,6 +91,12 @@ function taxonomy_node_tree_relation($tree) {
  * Sort terms in the tree.
  *
  * This function add terms on it's right place in the taxonomy tree.
+ *
+ * @param $tree
+ *   Tree with term objects to be changed (by reference).
+ *
+ * @param $term
+ *   Term object.
  */
 function taxonomy_node_tree_sort(&$tree, $term) {
   if ($term->parents[0] != 0 && isset($tree[$term->parents[0]])) {
@@ -86,6 +114,12 @@ function taxonomy_node_tree_sort(&$tree, $term) {
 
 /**
  * Sort a taxonomy tree to the right hierarchy.
+ *
+ * @param $tree
+ *   Tree with term objects.
+ *
+ * @return
+ *   Hierarchical term tree.
  */
 function taxonomy_node_tree_hierarchy($tree) {
   foreach ($tree as $term) {
@@ -94,6 +128,21 @@ function taxonomy_node_tree_hierarchy($tree) {
   return $tree;
 }
 
+/**
+ * Setup a full taxonomy node hierarchical tree.
+ *
+ * Build a tree with taxonomy terms with full dept
+ * and add child node information at each level.
+ *
+ * @param $nodes
+ *   Array with node objects.
+ *
+ * @param $terms
+ *   Array with term objects.
+ *
+ * @return
+ *  Hierarchical tree.
+ */
 function taxonomy_node_tree_build($nodes, $terms) {
   $tree = taxonomy_node_tree_index($nodes, $terms);
   $tree = taxonomy_node_tree_relation($tree);
@@ -102,8 +151,31 @@ function taxonomy_node_tree_build($nodes, $terms) {
 }
 
 /**
+ * Create a hierarchical representation of a vocabulary.
+ *
  * Version of taxonomy_get_tree() without caching.
- */
+ *
+ * @param $vid
+ *   Which vocabulary to generate the tree for.
+ *
+ * @param $parent
+ *   The term ID under which to generate the tree. If 0, generate the tree
+ *   for the entire vocabulary.
+ *
+ * @param $depth
+ *   Internal use only.
+ *
+ * @param $max_depth
+ *   The number of levels of the tree to return. Leave NULL to return all levels.
+ *
+ * @param $cache
+ *   Whether to use cache results.
+ *
+ * @return
+ *   An array of all term objects in the tree. Each term object is extended
+ *   to have "depth" and "parents" attributes in addition to its normal ones.
+ *   Results are statically cached.
+ */ 
 function taxonomy_node_tree_taxonomy_get_tree($vid, $parent = 0, $depth = -1, $max_depth = NULL, $cache = FALSE) {
   static $children, $parents, $terms;
 
-- 
cgit v1.2.3