[MPlayer-cvslog] CVS: main parser-cfg.c, 1.8, 1.9 parser-mecmd.c, 1.14, 1.15 parser-mecmd.h, 1.1, 1.2 parser-mpcmd.c, 1.27, 1.28 playtree.c, 1.23, 1.24 playtree.h, 1.8, 1.9 playtreeparser.c, 1.32, 1.33 playtreeparser.h, 1.5, 1.6

[Alban Bedel CVS]

CVS change done by Alban Bedel CVS

Update of /cvsroot/mplayer/main
In directory mail:/var2/tmp/cvs-serv18489

Modified Files:
	parser-cfg.c parser-mecmd.c parser-mecmd.h parser-mpcmd.c 
	playtree.c playtree.h playtreeparser.c playtreeparser.h 
Log Message:
Doxygen Attack! - Chapter 3


Index: parser-cfg.c
===================================================================
RCS file: /cvsroot/mplayer/main/parser-cfg.c,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- parser-cfg.c	24 Jan 2006 11:16:13 -0000	1.8
+++ parser-cfg.c	25 Apr 2006 01:26:10 -0000	1.9
@@ -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;
 }
+
+///@}

Index: parser-mecmd.c
===================================================================
RCS file: /cvsroot/mplayer/main/parser-mecmd.c,v
retrieving revision 1.14
retrieving revision 1.15
diff -u -r1.14 -r1.15
--- parser-mecmd.c	22 Apr 2006 21:30:34 -0000	1.14
+++ parser-mecmd.c	25 Apr 2006 01:26:10 -0000	1.15
@@ -1,3 +1,7 @@
+
+/// \file
+/// \ingroup ConfigParsers MEntry
+
 #include "config.h"
 
 #include <stdio.h>

Index: parser-mecmd.h
===================================================================
RCS file: /cvsroot/mplayer/main/parser-mecmd.h,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- parser-mecmd.h	12 Nov 2002 01:56:21 -0000	1.1
+++ parser-mecmd.h	25 Apr 2006 01:26:10 -0000	1.2
@@ -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);
 
+///@}

Index: parser-mpcmd.c
===================================================================
RCS file: /cvsroot/mplayer/main/parser-mpcmd.c,v
retrieving revision 1.27
retrieving revision 1.28
diff -u -r1.27 -r1.28
--- parser-mpcmd.c	22 Apr 2006 21:30:34 -0000	1.27
+++ parser-mpcmd.c	25 Apr 2006 01:26:10 -0000	1.28
@@ -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)
 {

Index: playtree.c
===================================================================
RCS file: /cvsroot/mplayer/main/playtree.c,v
retrieving revision 1.23
retrieving revision 1.24
diff -u -r1.23 -r1.24
--- playtree.c	5 Nov 2004 22:45:16 -0000	1.23
+++ playtree.c	25 Apr 2006 01:26:10 -0000	1.24
@@ -1,4 +1,7 @@
 
+/// \file
+/// \ingroup Playtree
+
 #include "config.h"
 #include <stdlib.h>
 #include <string.h>

Index: playtree.h
===================================================================
RCS file: /cvsroot/mplayer/main/playtree.h,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- playtree.h	5 Feb 2003 23:02:05 -0000	1.8
+++ playtree.h	25 Apr 2006 01:26:10 -0000	1.9
@@ -1,31 +1,54 @@
 
+/// \file
+/// \ingroup Playtree
+
 #ifndef __PLAYTREE_H
 #define __PLAYTREE_H
 
 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 (mplayer at fabian-franz.de)
+/// \defgroup PtAPI Playtree highlevel API
+/// \ingroup Playtree
+/// Highlevel API with pt-suffix to different from low-level API
+/// by Fabian Franz (mplayer at fabian-franz.de).
+///@{
 
-// 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
+
+///@}

Index: playtreeparser.c
===================================================================
RCS file: /cvsroot/mplayer/main/playtreeparser.c,v
retrieving revision 1.32
retrieving revision 1.33
diff -u -r1.32 -r1.33
--- playtreeparser.c	28 Oct 2005 22:12:20 -0000	1.32
+++ playtreeparser.c	25 Apr 2006 01:26:10 -0000	1.33
@@ -1,4 +1,7 @@
 
+/// \file
+/// \ingroup PlaytreeParser
+
 #include "config.h"
 #include <stdlib.h>
 #include <stdio.h>

Index: playtreeparser.h
===================================================================
RCS file: /cvsroot/mplayer/main/playtreeparser.h,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- playtreeparser.h	30 May 2003 17:53:03 -0000	1.5
+++ playtreeparser.h	25 Apr 2006 01:26:10 -0000	1.6
@@ -1,4 +1,13 @@
 
+/// \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
+
+///@}