diff playtree.h @ 18265:1a14fde7680d

Doxygen Attack! - Chapter 3

--- a/playtree.h	Mon Apr 24 23:48:15 2006 +0000
+++ b/playtree.h	Tue Apr 25 01:26:10 2006 +0000
@@ -1,3 +1,6 @@
+
+/// \file
+/// \ingroup Playtree
 
 #ifndef __PLAYTREE_H
 #define __PLAYTREE_H
@@ -5,27 +8,47 @@
 struct stream_st;
 struct m_config;
 
+/// \defgroup PlaytreeIterReturn Playtree iterator return code
+/// \ingroup PlaytreeIter
+///@{
 #define PLAY_TREE_ITER_ERROR 0
 #define PLAY_TREE_ITER_ENTRY 1
 #define PLAY_TREE_ITER_NODE  2
 #define PLAY_TREE_ITER_END 3
+///@}
 
+/// \defgroup PlaytreeEntryTypes Playtree entry types
+/// \ingroup Playtree
+///@{
 #define PLAY_TREE_ENTRY_NODE -1
 #define PLAY_TREE_ENTRY_DVD 0
 #define PLAY_TREE_ENTRY_VCD 1
 #define PLAY_TREE_ENTRY_TV    2
 #define PLAY_TREE_ENTRY_FILE  3
+///@}
 
-// Playtree flags
+
+/// \defgroup PlaytreeEntryFlags Playtree flags
+/// \ingroup Playtree
+///@{
+/// Play the item childs in random order.
 #define PLAY_TREE_RND  (1<<0)
-// Playtree flags used by the iter
+/// Playtree flags used by the iterator to mark items already "randomly" played.
 #define PLAY_TREE_RND_PLAYED  (1<<8)
+///@}
 
-// Iter mode
+/// \defgroup PlaytreeIterMode Playtree iterator mode
+/// \ingroup PlaytreeIter
+///@{
 #define PLAY_TREE_ITER_NORMAL 0
 #define PLAY_TREE_ITER_RND 1
+///@}
+
+/// \defgroup Playtree
+///@{
 
 typedef struct play_tree play_tree_t;
+/// \ingroup PlaytreeIter
 typedef struct play_tree_iter play_tree_iter_t;
 typedef struct play_tree_param play_tree_param_t;
 
@@ -48,6 +71,7 @@
 };
 
 
+/// Playtree item
 struct play_tree {
   play_tree_t* parent;
   play_tree_t* child;
@@ -61,147 +85,203 @@
   int entry_type;
   int flags;
 };
-  
+
+
+/// \defgroup PlaytreeIter Playtree iterator
+/// \ingroup Playtree
+///@{
+
+/// Playtree iterator
 struct play_tree_iter {
-  play_tree_t* root; // Iter root tree
-  play_tree_t* tree; // Current tree
-  struct m_config* config; 
-  int loop;  // Looping status
+  /// Root of the iterated tree.
+  play_tree_t* root;
+  /// Current position in the tree.
+  play_tree_t* tree;
+  /// \ref Config used.
+  struct m_config* config;
+  /// Looping status
+  int loop;
+  /// Selected file in the current item.
   int file;
+  /// Number of files in the current item.
   int num_files;
   int entry_pushed;
   int mode;
  
-  int* status_stack; //  loop/valid stack to save/revert status when we go up/down
-  int stack_size;  // status stack size
+  ///  loop/valid stack to save/revert status when we go up/down.
+  int* status_stack;
+  /// status stack size
+  int stack_size;
 };
+///@}
 
+/// Create a new empty playtree item.
 play_tree_t* 
 play_tree_new(void);
 
-// If childs is true free also the childs
+/// Free a playtree item.
+/** \param pt Item to free.
+ *  \param childs If non-zero the item's childs are recursively freed.
+ */
 void
 play_tree_free(play_tree_t* pt, int childs);
 
 
+/// Free an item and its siblings.
+/** \param pt Item to free.
+ *  \param childs If non-zero the items' childs are recursively freed.
+ */
 void
 play_tree_free_list(play_tree_t* pt, int childs);
 
 
-// Childs
+/// Set the childs of a playtree item.
 void
 play_tree_set_child(play_tree_t* pt, play_tree_t* child);
-// Or parent
+
+/// Set the parent of a playtree item.
 void
 play_tree_set_parent(play_tree_t* pt, play_tree_t* parent);
 
 
-// Add at end
+/// Append an item after its siblings.
 void
 play_tree_append_entry(play_tree_t* pt, play_tree_t* entry);
 
-// And on begining
+/// Prepend an item before its siblings.
 void
 play_tree_prepend_entry(play_tree_t* pt, play_tree_t* entry);
 
-// Insert after
+/// Insert an item right after a siblings.
 void
 play_tree_insert_entry(play_tree_t* pt, play_tree_t* entry);
 
-// Detach from the tree 
+/// Detach an item from the tree.
 void
 play_tree_remove(play_tree_t* pt, int free_it,int with_childs);
 
-
+/// Add a file to an item.
 void
 play_tree_add_file(play_tree_t* pt,char* file);
 
+/// Remove a file from an item.
 int
 play_tree_remove_file(play_tree_t* pt,char* file);
 
 
-// Val can be NULL
+/// Add a config paramter to an item.
 void
 play_tree_set_param(play_tree_t* pt, char* name, char* val);
 
+/// Remove a config parameter from an item.
 int
 play_tree_unset_param(play_tree_t* pt, char* name);
 
-// Set all paramter of source in dest
+/// Copy the config parameters from one item to another.
 void
 play_tree_set_params_from(play_tree_t* dest,play_tree_t* src);
 
-/// Iterator
+/// \addtogroup PlaytreeIter
+///@{
 
+/// Create a new iterator.
 play_tree_iter_t*
 play_tree_iter_new(play_tree_t* pt, struct m_config* config);
 
+/// Duplicate an iterator.
 play_tree_iter_t*
 play_tree_iter_new_copy(play_tree_iter_t* old);
 
+/// Free an iterator.
 void
 play_tree_iter_free(play_tree_iter_t* iter);
 
-// d is the direction : d > 0 == next , d < 0 == prev
-// with_node : TRUE == stop on nodes with childs, FALSE == go directly to the next child
-
+/// Step an iterator.
+/** \param iter The iterator.
+ *  \param d The direction: d > 0 == next , d < 0 == prev
+ *  \param with_node TRUE == stop on nodes with childs, FALSE == go directly to the next child
+ *  \return See \ref PlaytreeIterReturn.
+ */
 int 
 play_tree_iter_step(play_tree_iter_t* iter, int d,int with_nodes);
 
-int // Break a loop, etc
+/// Step up, usefull to break a loop, etc.
+/** \param iter The iterator.
+ *  \param d The direction: d > 0 == next , d < 0 == prev
+ *  \param with_node TRUE == stop on nodes with childs, FALSE == go directly to the next child
+ *  \return See \ref PlaytreeIterReturn.
+ */
+int
 play_tree_iter_up_step(play_tree_iter_t* iter, int d,int with_nodes);
 
-int // Enter a node child list
+/// Enter a node child list, only usefull when stopping on nodes.
+int
 play_tree_iter_down_step(play_tree_iter_t* iter, int d,int with_nodes);
 
+/// Get a file from the current item.
 char*
 play_tree_iter_get_file(play_tree_iter_t* iter, int d);
 
+///@}
+// PlaytreeIter group
+
+/// Create a playtree from a playlist file.
+/** \ingroup PlaytreeParser
+ */
 play_tree_t*
 parse_playtree(struct stream_st *stream, int forced);
 
+/// Clean a tree by destroying all empty elements.
 play_tree_t*
 play_tree_cleanup(play_tree_t* pt);
 
+/// Create a playtree from a playlist file.
+/** \ingroup PlaytreeParser
+ */
 play_tree_t*
 parse_playlist_file(char* file);
 
-// Highlevel API with pt-suffix to different from low-level API
-// by Fabian Franz ([e-mail])
+/// \defgroup PtAPI Playtree highlevel API
+/// \ingroup Playtree
+/// Highlevel API with pt-suffix to different from low-level API
+/// by Fabian Franz ([e-mail]).
+///@{
 
-// Cleanups pt and creates a new iter
+/// Cleanups pt and creates a new iter.
 play_tree_iter_t* pt_iter_create(play_tree_t** pt, struct m_config* config);
 
-// Frees the iter
+/// Frees the iter.
 void pt_iter_destroy(play_tree_iter_t** iter);
 
-// Gets the next available file in the direction (d=-1 || d=+1)
+/// Gets the next available file in the direction (d=-1 || d=+1).
 char* pt_iter_get_file(play_tree_iter_t* iter, int d);
 
-// Two Macros that implement forward and backward direction
+// Two Macros that implement forward and backward direction.
 #define pt_iter_get_next_file(iter) pt_iter_get_file(iter, 1)
 #define pt_iter_get_prev_file(iter) pt_iter_get_file(iter, -1)
 
-// Inserts entry into the playtree
+/// Inserts entry into the playtree.
 void pt_iter_insert_entry(play_tree_iter_t* iter, play_tree_t* entry);
 
-//Replaces current entry in playtree with entry
-//by doing insert and remove
+/// Replaces current entry in playtree with entry by doing insert and remove.
 void pt_iter_replace_entry(play_tree_iter_t* iter, play_tree_t* entry);
 
-// Adds a new file to the playtree, 
-// if it is not valid it is created
+/// Adds a new file to the playtree, if it is not valid it is created.
 void pt_add_file(play_tree_t** ppt, char* filename);
 
-// Performs a convert to playtree-syntax, by concat path/file
-// and performs pt_add_file
+/// \brief Performs a convert to playtree-syntax, by concat path/file 
+/// and performs pt_add_file
 void pt_add_gui_file(play_tree_t** ppt, char* path, char* file);
 
-//Two macros to use only the iter and not the other things
+// Two macros to use only the iter and not the other things.
 #define pt_iter_add_file(iter, filename) pt_add_file(&iter->tree, filename)
 #define pt_iter_add_gui_file(iter, path, name) pt_add_gui_file(&iter->tree, path, name)
 
-// Resets the iter and goes back to head
+/// Resets the iter and goes back to head.
 void pt_iter_goto_head(play_tree_iter_t* iter);
 
+///@}
+
 #endif
+
+///@}