COLLECTION Create reference to the top level collection

This patch adds ability to create a reference to the top
level collection.
Previously one could get reference only to collection
inside other collection. With this change it becomes
possible to have two pointers to the same top level
collection from multiple places.

COLLECTION Adding comment.

COLLECTION: Some tracing

1 files changed, 4 insertions, 2 deletions

diff --git a/collection/collection.h b/collection/collection.h
index 2e2fe64..665d5f0 100644
--- a/collection/collection.h
+++ b/collection/collection.h
@@ -686,8 +686,10 @@ int col_is_item_in_collection(struct collection_item *ci,   /* Collection to fin
                               int *found);                  /* Boolean that turns to nonzero if the match is found */
 
 
-/* Get collection - get a pointer to a collection included into another collection */
-/* Delete extracted collection after use to decrease reference count. */
+/* Get collection - get a pointer to a collection included into another collection.
+ * If the collection_to_find is NULL function reterns a reference to the top level collection.
+ * Delete extracted collection after use to decrease reference count.
+ */
 int col_get_collection_reference(struct collection_item *ci,          /* High level collection */
                                  struct collection_item **acceptor,   /* The pointer that will accept extracted handle */
                                  const char *collection_to_find);     /* Name to of the collection */