Improve treeview documentation comments

1 files changed, 130 insertions, 64 deletions

diff --git a/desktop/treeview.h b/desktop/treeview.h
index 518f045aa..0dbde1119 100644
--- a/desktop/treeview.h
+++ b/desktop/treeview.h
@@ -37,6 +37,10 @@ struct core_window_callback_table;
 typedef struct treeview treeview;
 typedef struct treeview_node treeview_node;
 
+
+/**
+ * treeview node type
+ */
 enum treeview_node_type {
 	TREE_NODE_NONE		= 0,		/**< No node  */
 	TREE_NODE_ROOT		= (1 << 0),	/**< Node is treeview's root */
@@ -44,18 +48,29 @@ enum treeview_node_type {
 	TREE_NODE_ENTRY		= (1 << 2)	/**< Node is an entry */
 };
 
+
+/**
+ * Relationship between nodes
+ */
 enum treeview_relationship {
 	TREE_REL_FIRST_CHILD,
 	TREE_REL_NEXT_SIBLING
-};					/**< Relationship between nodes */
+};
 
+
+/**
+ * Node change handling options
+ */
 typedef enum {
 	TREE_OPTION_NONE		= (0),		/* No flags set */
 	TREE_OPTION_SPECIAL_DIR		= (1 << 0),	/* Special folder */
 	TREE_OPTION_SUPPRESS_RESIZE	= (1 << 1),	/* Suppress callback */
 	TREE_OPTION_SUPPRESS_REDRAW	= (1 << 2)	/* Suppress callback */
-} treeview_node_options_flags;		/**< Node change handling options */
+} treeview_node_options_flags;
 
+/**
+ * treeview control flags
+ */
 typedef enum {
 	TREEVIEW_NO_FLAGS	= (0),		/**< No flags set */
 	TREEVIEW_NO_MOVES	= (1 << 0),	/**< No node drags */
@@ -64,20 +79,28 @@ typedef enum {
 	TREEVIEW_DEL_EMPTY_DIRS	= (1 << 2)	/**< Delete dirs on empty */
 } treeview_flags;
 
+/**
+ * treeview message types
+ */
 enum treeview_msg {
 	TREE_MSG_NODE_DELETE,		/**< Node to be deleted */
 	TREE_MSG_NODE_EDIT,		/**< Node to be edited */
 	TREE_MSG_NODE_LAUNCH		/**< Node to be launched */
 };
+
+
+/**
+ * treeview message
+ */
 struct treeview_node_msg {
 	enum treeview_msg msg; /**< The message type */
 	union {
 		struct {
-			bool user; /* True iff delete by user interaction */
+			bool user; /**< True iff delete by user interaction */
 		} delete;
 		struct {
-			lwc_string *field; /* The field being edited */
-			const char *text;  /* The proposed new value */
+			lwc_string *field; /**< The field being edited */
+			const char *text;  /**< The proposed new value */
 		} node_edit; /* Client may call treeview_update_node_* */
 		struct {
 			browser_mouse_state mouse; /* Button / modifier used */
@@ -85,6 +108,10 @@ struct treeview_node_msg {
 	} data; /**< The message data. */
 };
 
+
+/**
+ * treeview field flags
+ */
 enum treeview_field_flags {
 	TREE_FLAG_NONE		= 0,		/**< No flags set */
 	TREE_FLAG_ALLOW_EDIT	= (1 << 0),	/**< Whether allow edit field */
@@ -92,11 +119,20 @@ enum treeview_field_flags {
 	TREE_FLAG_SHOW_NAME	= (1 << 2),	/**< Whether field name shown */
 	TREE_FLAG_COPY_TEXT	= (1 << 3)	/**< Whether to copy to clipb */
 };
+
+
+/**
+ * Treeview field description
+ */
 struct treeview_field_desc {
 	lwc_string *field;			/**< A treeview field name */
 	enum treeview_field_flags flags;	/**< Flags for field */
-}; /**< Treeview field description */
+};
 
+
+/**
+ * Treeview field data
+ */
 struct treeview_field_data {
 	lwc_string *field;		/**< Field name */
 	const char *value;		/**< Field value */
@@ -104,10 +140,14 @@ struct treeview_field_data {
 };
 
 
+/**
+ * Client callbacks for events concerning nodes
+ */
 struct treeview_callback_table {
 	nserror (*folder)(struct treeview_node_msg msg, void *data);
 	nserror (*entry)(struct treeview_node_msg msg, void *data);
-}; /**< Client callbacks for events concerning nodes */
+};
+
 
 /**
  * Prepare treeview module for treeview usage
@@ -116,6 +156,7 @@ struct treeview_callback_table {
  */
 nserror treeview_init(void);
 
+
 /**
  * Finalise the treeview module (all treeviews must have been destroyed first)
  *
@@ -123,9 +164,18 @@ nserror treeview_init(void);
  */
 nserror treeview_fini(void);
 
+
 /**
  * Create a treeview
  *
+ * The fields array order is as follows (N = n_fields):
+ *
+ *    fields[0]			Main field for entries (shown when not expanded)
+ *    fields[1]...fields[N-2]	Additional fields for entries
+ *    fields[N-1]		Field for folder nodes
+ *
+ * So fields[0] and fields[N-1] have TREE_FLAG_DEFAULT set.
+ *
  * \param tree		Returns created treeview object
  * \param callbacks	Treeview client node event callbacks
  * \param n_fields	Number of treeview fields (see description)
@@ -134,20 +184,13 @@ nserror treeview_fini(void);
  * \param cw		The core_window in which the treeview is shown
  * \param flags		Treeview behaviour flags
  * \return NSERROR_OK on success, appropriate error otherwise
- *
- * The fields array order is as follows (N = n_fields):
- *
- *    fields[0]			Main field for entries (shown when not expanded)
- *    fields[1]...fields[N-2]	Additional fields for entries
- *    fields[N-1]		Field for folder nodes
- *
- * So fields[0] and fields[N-1] have TREE_FLAG_DEFAULT set.
  */
 nserror treeview_create(treeview **tree,
-		const struct treeview_callback_table *callbacks,
-		int n_fields, struct treeview_field_desc fields[],
-		const struct core_window_callback_table *cw_t,
-		struct core_window *cw, treeview_flags flags);
+			const struct treeview_callback_table *callbacks,
+			int n_fields, struct treeview_field_desc fields[],
+			const struct core_window_callback_table *cw_t,
+			struct core_window *cw, treeview_flags flags);
+
 
 /**
  * Attach a treeview to a corewindow.
@@ -160,45 +203,50 @@ nserror treeview_create(treeview **tree,
  * \return NSERROR_OK on success, appropriate error otherwise
  */
 nserror treeview_cw_attach(treeview *tree,
-		const struct core_window_callback_table *cw_t,
-		struct core_window *cw);
+			   const struct core_window_callback_table *cw_t,
+			   struct core_window *cw);
+
 
 /**
  * Detach a treeview from a corewindow
  *
- * \param tree		Treeview object
+ * \param tree Treeview object
  * \return NSERROR_OK on success, appropriate error otherwise
  */
 nserror treeview_cw_detach(treeview *tree);
 
+
 /**
  * Destroy a treeview object
  *
- * \param tree		Treeview object to destroy
- * \return NSERROR_OK on success, appropriate error otherwise
- *
  * Will emit folder and entry deletion msg callbacks for all nodes in treeview.
+ *
+ * \param tree Treeview object to destroy
+ * \return NSERROR_OK on success, appropriate error otherwise
  */
 nserror treeview_destroy(treeview *tree);
 
+
 /**
  * Find a releation for node creation.
  *
+ * If at_y is set, we find a relation that will put the created node at that
+ * position.
+ *
+ * If at_y is unset, we find a relation that would put the node below the first
+ * selected node, or at the end of the treeview if no nodes selected.
+ *
  * \param tree		Treeview object in which to create folder
  * \param relation	Existing node to insert as relation of, or NULL
  * \param rel		Folder's relationship to relation
  * \param at_y		Iff true, insert at y-offest
  * \param y		Y-offset in px from top of hotlist.  Ignored if (!at_y).
  * \return NSERROR_OK on success, appropriate error otherwise
- *
- * If at_y is set, we find a relation that will put the created node at that
- * position.
- *
- * If at_y is unset, we find a relation that would put the node below the first
- * selected node, or at the end of the treeview if no nodes selected.
  */
 nserror treeview_get_relation(treeview *tree, treeview_node **relation,
-		enum treeview_relationship *rel, bool at_y, int y);
+			      enum treeview_relationship *rel,
+			      bool at_y, int y);
+
 
 /**
  * Create a folder node in given treeview
@@ -217,11 +265,13 @@ nserror treeview_get_relation(treeview *tree, treeview_node **relation,
  * If relation is NULL, will insert as child of root node.
  */
 nserror treeview_create_node_folder(treeview *tree,
-		treeview_node **folder,
-		treeview_node *relation,
-		enum treeview_relationship rel,
-		const struct treeview_field_data *field,
-		void *data, treeview_node_options_flags flags);
+				    treeview_node **folder,
+				    treeview_node *relation,
+				    enum treeview_relationship rel,
+				    const struct treeview_field_data *field,
+				    void *data,
+				    treeview_node_options_flags flags);
+
 
 /**
  * Create an entry node in given treeview
@@ -240,11 +290,13 @@ nserror treeview_create_node_folder(treeview *tree,
  * If relation is NULL, will insert as child of root node.
  */
 nserror treeview_create_node_entry(treeview *tree,
-		treeview_node **entry,
-		treeview_node *relation,
-		enum treeview_relationship rel,
-		const struct treeview_field_data fields[],
-		void *data, treeview_node_options_flags flags);
+				   treeview_node **entry,
+				   treeview_node *relation,
+				   enum treeview_relationship rel,
+				   const struct treeview_field_data fields[],
+				   void *data,
+				   treeview_node_options_flags flags);
+
 
 /**
  * Update an folder node in given treeview
@@ -258,9 +310,10 @@ nserror treeview_create_node_entry(treeview *tree,
  * Field name must match name past in treeview_create fields[N-1].
  */
 nserror treeview_update_node_folder(treeview *tree,
-		treeview_node *folder,
-		const struct treeview_field_data *field,
-		void *data);
+				    treeview_node *folder,
+				    const struct treeview_field_data *field,
+				    void *data);
+
 
 /**
  * Update an entry node in given treeview
@@ -274,9 +327,9 @@ nserror treeview_update_node_folder(treeview *tree,
  * Fields array names must match names past in treeview_create fields[0...N-2].
  */
 nserror treeview_update_node_entry(treeview *tree,
-		treeview_node *entry,
-		const struct treeview_field_data fields[],
-		void *data);
+				   treeview_node *entry,
+				   const struct treeview_field_data fields[],
+				   void *data);
 
 
 /**
@@ -289,12 +342,19 @@ nserror treeview_update_node_entry(treeview *tree,
  * \return NSERROR_OK on success, or appropriate error otherwise
  */
 typedef nserror (*treeview_walk_cb)(void *ctx, void *node_data,
-		enum treeview_node_type type, bool *abort);
+				    enum treeview_node_type type, bool *abort);
+
 
 /**
  * Walk (depth first) a treeview subtree, calling a callback at each node of
  * required type.
  *
+ * Example usage: To export a treeview as XML, XML elements can be opened in
+ * enter_cb, and closed in leave_cb.
+ *
+ * Note, if deleting returned node in enter_cb, the walk must be terminated by
+ * setting abort to true.
+ *
  * \param tree		Treeview object to walk
  * \param root		Root node to walk tree from (or NULL for tree root)
  * \param enter_cb	Function to call on entering nodes, or NULL
@@ -302,16 +362,11 @@ typedef nserror (*treeview_walk_cb)(void *ctx, void *node_data,
  * \param ctx		Client context, passed back to callback function
  * \param type		The node type(s) of interest
  * \return NSERROR_OK on success, or appropriate error otherwise
- *
- * Example usage: To export a treeview as XML, XML elements can be opened in
- * enter_cb, and closed in leave_cb.
- *
- * Note, if deleting returned node in enter_cb, the walk must be terminated by
- * setting abort to true.
  */
 nserror treeview_walk(treeview *tree, treeview_node *root,
-		treeview_walk_cb enter_cb, treeview_walk_cb leave_cb,
-		void *ctx, enum treeview_node_type type);
+		      treeview_walk_cb enter_cb, treeview_walk_cb leave_cb,
+		      void *ctx, enum treeview_node_type type);
+
 
 /**
  * Delete a treeview node
@@ -324,7 +379,8 @@ nserror treeview_walk(treeview *tree, treeview_node *root,
  * Will emit folder or entry deletion msg callback.
  */
 nserror treeview_delete_node(treeview *tree, treeview_node *n,
-		treeview_node_options_flags flags);
+			     treeview_node_options_flags flags);
+
 
 /**
  * Expand a treeview node
@@ -335,6 +391,7 @@ nserror treeview_delete_node(treeview *tree, treeview_node *n,
  */
 nserror treeview_node_expand(treeview *tree, treeview_node *node);
 
+
 /**
  * Contract a treeview node
  *
@@ -344,6 +401,7 @@ nserror treeview_node_expand(treeview *tree, treeview_node *node);
  */
 nserror treeview_node_contract(treeview *tree, treeview_node *node);
 
+
 /**
  * Expand a treeview's nodes
  *
@@ -353,6 +411,7 @@ nserror treeview_node_contract(treeview *tree, treeview_node *node);
  */
 nserror treeview_expand(treeview *tree, bool only_folders);
 
+
 /**
  * Contract a treeview's nodes
  *
@@ -362,6 +421,7 @@ nserror treeview_expand(treeview *tree, bool only_folders);
  */
 nserror treeview_contract(treeview *tree, bool all);
 
+
 /**
  * Redraw a treeview object
  *
@@ -372,7 +432,8 @@ nserror treeview_contract(treeview *tree, bool all);
  * \param ctx		Current redraw context
  */
 void treeview_redraw(treeview *tree, int x, int y, struct rect *clip,
-		const struct redraw_context *ctx);
+		     const struct redraw_context *ctx);
+
 
 /**
  * Key press handling for treeviews.
@@ -383,6 +444,7 @@ void treeview_redraw(treeview *tree, int x, int y, struct rect *clip,
  */
 bool treeview_keypress(treeview *tree, uint32_t key);
 
+
 /**
  * Handles all kinds of mouse action
  *
@@ -392,16 +454,18 @@ bool treeview_keypress(treeview *tree, uint32_t key);
  * \param y		Y coordinate
  */
 void treeview_mouse_action(treeview *tree,
-		browser_mouse_state mouse, int x, int y);
+			   browser_mouse_state mouse, int x, int y);
+
 
 /**
  * Determine whether treeview has a selection
  *
- * \param tree		Treeview object to delete node from
+ * \param tree Treeview object to delete node from
  * \return true iff treeview has a selection
  */
 bool treeview_has_selection(treeview *tree);
 
+
 /**
  * Get the first selected node
  *
@@ -410,19 +474,21 @@ bool treeview_has_selection(treeview *tree);
  * \return node type of first selected node.
  */
 enum treeview_node_type treeview_get_selection(treeview *tree,
-		void **node_data);
+					       void **node_data);
+
 
 /**
  * Edit the first selected node
  *
- * \param tree		Treeview object to edit selected node in
+ * \param tree Treeview object to edit selected node in
  */
 void treeview_edit_selection(treeview *tree);
 
+
 /**
  * Find current height of a treeview
  *
- * \param tree		Treeview object to find height of
+ * \param tree Treeview object to find height of
  * \return height of treeview in px
  */
 int treeview_get_height(treeview *tree);