1 files changed, 115 insertions, 10 deletions

diff --git a/include/dtree/dyn_tree.h b/include/dtree/dyn_tree.h
index e1db1d6..cfd7239 100644
--- a/include/dtree/dyn_tree.h
+++ b/include/dtree/dyn_tree.h
@@ -30,8 +30,9 @@
 extern "C" {
 #endif
 
+/* Type that determines what data is stored inside a tree-node */
 typedef enum {
-    UNSET, LITERAL, NUMERAL, RECURSIVE, PAIR
+    UNSET, LITERAL, NUMERAL, RECURSIVE, PAIR, POINTER
 } dt_uni_t;
 
 typedef struct dtree {
@@ -40,35 +41,139 @@ typedef struct dtree {
     union {
         char                *literal;
         int                 numeral;
-        struct dtree     *(*recursive);
+        struct dtree        *(*recursive);
+        void                *pointer;
     } payload;
 } dtree;
 
-/** Malloc a new dtree object */
+
+/**
+ * Malloc a new dtree object
+ *
+ * @param data Reference pointer to dtree element
+ * @return
+ */
 dt_err dtree_malloc(dtree *(*data));
 
+
+/**
+ * Reset the type of a node and free child data
+ *
+ * @param data
+ * @return
+ */
 dt_err dtree_resettype(dtree *data);
 
-/** Set the data element to a literal and save it's length */
+
+/**
+ * Set the data element to a literal and save it's length
+ *
+ * @param data Reference to a dtree object
+ * @param literal String to store
+ * @param length TRUE string length to use.
+ * @return
+ */
 dt_err dtree_addliteral(dtree *data, const char *literal, size_t length);
 
-/** Set the data element to a numeral */
+
+/**
+ * Set the data element to a numeral
+ *
+ * @param data Reference to a dtree object
+ * @param numeral Number to store
+ * @return
+ */
 dt_err dtree_addnumeral(dtree *data, int numeral);
 
-/** Add two new elements as a PAIR node under an existing node */
+
+/**
+ * Add two new elements as a PAIR node under an existing node
+ *
+ * @param data dtree node to become the sub-root
+ * @param key Reference pointer to the key node
+ * @param value Reference pointer to the value node
+ * @return
+ */
 dt_err dtree_addpair(dtree *data, dtree *(*key), dtree *(*value));
 
-/** Add a new data element to the resursive data store */
+
+/**
+ * Add a new data element to the resursive data store
+ *
+ * @param data Root reference
+ * @param new_data Reference pointer to a new dtree node
+ * @return
+ */
 dt_err dtree_addrecursive(dtree *data, dtree *(*new_data));
 
+
+/**
+ * This function enables you to store your own structures in a node. It however
+ * also requires you to do some of your own memory management.
+ *
+ * WARNING: Can leak memory if pointer is previously set!
+ *
+ * To make sure that this function CAN NOT leak memory you should run
+ * "dtree_resettype" on the root element to remove the pointer.
+ *
+ * Also make sure that no other part of your application will use the
+ * pointer at a later date!
+ *
+ * @param data Root reference
+ * @param ptr A pointer to store in this node
+ * @return
+ */
+dt_err dtree_addpointer(dtree *data, void *ptr);
+
+
+/**
+ * A retrieve function to get data back from a node that doesn't require
+ * you to manually access parts of the struct.
+ *
+ * Needs to be provided with a reference to a pointer that can then be
+ * written to. You can make the reference type specific if you know
+ * what kind of data you're expecting or leave it as a void* to let
+ * libdyntree do the casting for you.
+ *
+ * @param data Node reference to access
+ * @param val Reference pointer to write into
+ * @return
+ */
 dt_err dtree_get(dtree *data, void *(*val));
 
-const char *dtree_dtype(dt_uni_t type);
 
-/** Prints*/
+/**
+ * Return the type of a node as plain text
+ *
+ * @param data
+ * @return
+ */
+const char *dtree_dtype(dtree *data);
+
+
+/**
+ * Prints the data dtree object and all of its children
+ *
+ * @param data
+ */
 void dtree_print(dtree *data);
 
-/** Will free all memory allocated by this element and it's children */
+/**
+ * Will free the data reference and all of it's children. It will however NOT
+ * touch pointers to objects that weren't allocated by libdyntree!
+ *
+ * @param data
+ * @return
+ */
+dt_err dtree_free_shallow(dtree *data);
+
+/**
+ * Like #{dtree_free_shallow} but will also remove structs that
+ * weren't allocated by libdyntree
+ *
+ * @param data
+ * @return
+ */
 dt_err dtree_free(dtree *data);
 
 #ifdef __cplusplus