changeset 18265:1a14fde7680d

Doxygen Attack! - Chapter 3

--- a/parser-cfg.c	Mon Apr 24 23:48:15 2006 +0000
+++ b/parser-cfg.c	Tue Apr 25 01:26:10 2006 +0000
@@ -1,3 +1,12 @@
+
+/// \defgroup ConfigParsers Config parsers
+///
+/// The \ref ConfigParsers make use of the \ref Config to setup the config variables,
+/// the command line parsers also build the playlist.
+///@{
+
+/// \file
+
 #include "config.h"
 
 #include <stdio.h>
@@ -14,10 +23,17 @@
 #include "m_option.h"
 #include "m_config.h"
 
+/// Maximal include depth.
 #define MAX_RECURSION_DEPTH	8
 
+/// Current include depth.
 static int recursion_depth = 0;
 
+/// Setup the \ref Config from a config file.
+/** \param config The config object.
+ *  \param conffile Path to the config file.
+ *  \return 1 on sucess, -1 on error.
+ */
 int m_config_parse_config_file(m_config_t* config, char *conffile)
 {
 #define PRINT_LINENUM	mp_msg(MSGT_CFGPARSER,MSGL_V,"%s(%d): ", conffile, line_num)
@@ -226,3 +242,5 @@
 	--recursion_depth;
 	return ret;
 }
+
+///@}

--- a/parser-mecmd.c	Mon Apr 24 23:48:15 2006 +0000
+++ b/parser-mecmd.c	Tue Apr 25 01:26:10 2006 +0000
@@ -1,3 +1,7 @@
+
+/// \file
+/// \ingroup ConfigParsers MEntry
+
 #include "config.h"
 
 #include <stdio.h>

--- a/parser-mecmd.h	Mon Apr 24 23:48:15 2006 +0000
+++ b/parser-mecmd.h	Tue Apr 25 01:26:10 2006 +0000
@@ -1,18 +1,31 @@
 
-/// A simple parser with per-entry settings.
+/// \file
+/// \ingroup ConfigParsers MEntry
+/// \brief A simple parser with per-entry settings.
 
+/// \defgroup MEntry MEncoder's playlist
+///@{
+
+/// Playlist entry
 typedef struct m_entry_st {
-  char* name; // Filename, url or whatever
-  char** opts; // NULL terminated list of name,val pairs 
+  /// Filename, url or whatever.
+  char* name;
+  /// NULL terminated list of name,val pairs.
+  char** opts;
 } m_entry_t;
 
-// Free a list returned by m_config_parse_command_line
+/// Free a list returned by \ref m_config_parse_me_command_line.
 void
 m_entry_list_free(m_entry_t* lst);
-// Use this when you switch to another entry
+
+/// Helper to set all config options from an entry.
 int
 m_entry_set_options(m_config_t *config, m_entry_t* entry);
 
+/// Setup the \ref Config from command line arguments and build a playlist.
+/** \ingroup ConfigParsers
+ */
 m_entry_t*
 m_config_parse_me_command_line(m_config_t *config, int argc, char **argv);
 
+///@}

--- a/parser-mpcmd.c	Mon Apr 24 23:48:15 2006 +0000
+++ b/parser-mpcmd.c	Tue Apr 25 01:26:10 2006 +0000
@@ -1,3 +1,7 @@
+
+/// \file
+/// \ingroup ConfigParsers Playtree
+
 #include "config.h"
 
 #include <stdio.h>
@@ -56,6 +60,9 @@
     *last_entryp = entry;
 }
 
+/// Setup the \ref Config from command line arguments and build a playtree.
+/** \ingroup ConfigParsers
+ */
 play_tree_t*
 m_config_parse_mp_command_line(m_config_t *config, int argc, char **argv)
 {

--- a/playtree.c	Mon Apr 24 23:48:15 2006 +0000
+++ b/playtree.c	Tue Apr 25 01:26:10 2006 +0000
@@ -1,3 +1,6 @@
+
+/// \file
+/// \ingroup Playtree
 
 #include "config.h"
 #include <stdlib.h>

--- 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
+
+///@}

--- a/playtreeparser.c	Mon Apr 24 23:48:15 2006 +0000
+++ b/playtreeparser.c	Tue Apr 25 01:26:10 2006 +0000
@@ -1,3 +1,6 @@
+
+/// \file
+/// \ingroup PlaytreeParser
 
 #include "config.h"
 #include <stdlib.h>

--- a/playtreeparser.h	Mon Apr 24 23:48:15 2006 +0000
+++ b/playtreeparser.h	Tue Apr 25 01:26:10 2006 +0000
@@ -1,3 +1,12 @@
+
+/// \defgroup PlaytreeParser Playtree parser
+/// \ingroup Playtree
+///
+/// The playtree parser allow to read various playlist formats. It read from
+/// stream allowing to handle playlist from local files and the network.
+///@{
+
+/// \file
 
 #ifndef __PLAYTREEPARSER_H
 #define __PLAYTREEPARSER_H
@@ -11,17 +20,33 @@
   int deep,keep;
 } play_tree_parser_t;
 
-
+/// Create a new parser.
+/** \param stream The stream to read from.
+ *  \param deep Parser depth. Some format allow including other files,
+ *              this is used to track the inclusion depth.
+ *  \return The new parser.
+ */
 play_tree_parser_t*
 play_tree_parser_new(struct stream_st* stream,int deep);
 
+/// Destroy a parser.
 void
 play_tree_parser_free(play_tree_parser_t* p);
 
+/// Build a playtree from the playlist opened with the parser.
+/** \param p The parser.
+ *  \param forced If non-zero the playlist file was explicitly
+ *                given by the user, allow falling back on
+ *                one filename per line playlist.
+ *  \return A new playtree or NULL on error.
+ */
 play_tree_t*
 play_tree_parser_get_play_tree(play_tree_parser_t* p, int forced);
 
+/// Wrapper for play_tree_add_basepath (add base path from file).
 void
 play_tree_add_bpf(play_tree_t* pt, char* filename);
 
 #endif
+
+///@}