# HG changeset patch # User albeu # Date 1145928370 0 # Node ID 1a14fde7680d78bab561d04a1b63dbc475400eea # Parent bbb63cea568b77c75c51ee0f4e5fdb1eb3cba584 Doxygen Attack! - Chapter 3 diff -r bbb63cea568b -r 1a14fde7680d parser-cfg.c --- 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 @@ -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; } + +///@} diff -r bbb63cea568b -r 1a14fde7680d parser-mecmd.c --- 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 diff -r bbb63cea568b -r 1a14fde7680d parser-mecmd.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); +///@} diff -r bbb63cea568b -r 1a14fde7680d parser-mpcmd.c --- 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 @@ -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) { diff -r bbb63cea568b -r 1a14fde7680d playtree.c --- 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 diff -r bbb63cea568b -r 1a14fde7680d playtree.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 (mplayer@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@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 + +///@} diff -r bbb63cea568b -r 1a14fde7680d playtreeparser.c --- 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 diff -r bbb63cea568b -r 1a14fde7680d playtreeparser.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 + +///@}