. added comments to src/interface/intf_plst.c and include/intf_plst.h
   so that people understand how the playlist works.
 . updated the TODO list (34 items to do, 41 done !)

TODO

@@ -74,7 +74,7 @@ Difficulty: Hard
 Urgency: Normal
 Description: Make input plugins dynamically loadable
  With a probe() function, and stuff...
-Status: Todo
+Status: Done 7 Feb 2001 (sam)
 
 Task: 0x45
 Difficulty: Guru
@@ -375,7 +375,7 @@ Description: Implement pause
  displaying and sound playback, but the streams continues to
  be decoded. One will have to do a file implementation as
  well as a network implementation.
-Status: Todo
+Status: Done 8 Feb 2001 (Meuuh)
 
 Task: 0x20
 Difficulty: Hard
@@ -432,7 +432,6 @@ Task: 0x1a
 Difficulty: Easy
 Urgency: Normal
 Description: Make interface more responsive
-Status: Todo
  When in "waiting for stream" mode, the interface is refreshed
  every 5 seconds. This is too long, and can be confusing for
  the user. Make it refresh at least after a keyboard/mouse event.
@@ -642,7 +641,7 @@ Description: Playlist API
  one after the other. We need a smarter way to handle this,
  through AddFile(), MoveFile(), etc. functions. input_file
  has to be modified to support this as well.
-Status: Todo
+Status: Done 8 Feb 2001 (sam)
 
 Task: 0x02
 Difficulty: Medium
@@ -669,5 +668,3 @@ Description: Splash screen
  the "waiting for stream" message.
 Status: Todo
 
-
-

include/intf_plst.h

@@ -20,6 +20,9 @@
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111, USA.
  *****************************************************************************/
 
+/*****************************************************************************
+ * playlist_item_t: playlist item
+ *****************************************************************************/
 typedef struct playlist_item_s
 {
     char*             psz_name;
@@ -27,6 +30,13 @@ typedef struct playlist_item_s
     int               i_status; /* unused yet */
 } playlist_item_t;
 
+/*****************************************************************************
+ * playlist_t: playlist structure
+ *****************************************************************************
+ * The structure contains information about the size and browsing mode of
+ * the playlist, a change lock, a dynamic array of playlist items, and a
+ * current item which is an exact copy of one of the array members.
+ *****************************************************************************/
 typedef struct playlist_s
 {
     int                   i_index;                          /* current index */
@@ -41,7 +51,7 @@ typedef struct playlist_s
     playlist_item_t*      p_item;
 } playlist_t;
 
-/* Used by playlist_Add */
+/* Used by intf_PlstAdd */
 #define PLAYLIST_START            0
 #define PLAYLIST_END             -1
 
@@ -54,11 +64,14 @@ typedef struct playlist_s
 #define PLAYLIST_RANDOM           3                          /* Shuffle play */
 #define PLAYLIST_REVERSE_RANDOM  -3                  /* Reverse shuffle play */
 
-playlist_t * playlist_Create   ( void );
-void         playlist_Init     ( playlist_t * p_playlist );
-int          playlist_Add      ( playlist_t * p_playlist,
+/*****************************************************************************
+ * Prototypes
+ *****************************************************************************/
+playlist_t * intf_PlstCreate   ( void );
+void         intf_PlstInit     ( playlist_t * p_playlist );
+int          intf_PlstAdd      ( playlist_t * p_playlist,
                                  int i_pos, char * psz_item );
-void         playlist_Next     ( playlist_t * p_playlist );
-void         playlist_Prev     ( playlist_t * p_playlist );
-void         playlist_Destroy  ( playlist_t * p_playlist );
+void         intf_PlstNext     ( playlist_t * p_playlist );
+void         intf_PlstPrev     ( playlist_t * p_playlist );
+void         intf_PlstDestroy  ( playlist_t * p_playlist );
 

src/interface/interface.c

@@ -186,7 +186,7 @@ void intf_Run( intf_thread_t *p_intf )
     while( !p_intf->b_die )
     {
         /* Select the next playlist item */
-        playlist_Next( p_main->p_playlist );
+        intf_PlstNext( p_main->p_playlist );
 
         if( p_main->p_playlist->i_index == -1 )
         {

src/interface/intf_plst.c

@@ -36,9 +36,17 @@
 
 #include "main.h"
 
+/*****************************************************************************
+ * Local prototypes
+ *****************************************************************************/
 static void NextItem( playlist_t * p_playlist );
 
-playlist_t * playlist_Create ( void )
+/*****************************************************************************
+ * intf_PlstCreate: create playlist
+ *****************************************************************************
+ * Create a playlist structure.
+ *****************************************************************************/
+playlist_t * intf_PlstCreate ( void )
 {
     playlist_t *p_playlist;
 
@@ -54,11 +62,16 @@ playlist_t * playlist_Create ( void )
     return( p_playlist );
 }
 
-void playlist_Init ( playlist_t * p_playlist )
+/*****************************************************************************
+ * intf_PlstInit: initialize playlist
+ *****************************************************************************
+ * Initialize a playlist structure.
+ *****************************************************************************/
+void intf_PlstInit ( playlist_t * p_playlist )
 {
     vlc_mutex_init( &p_playlist->change_lock );
 
-    p_playlist->i_index = -1; /* -1 means we are not playing anything yet */
+    p_playlist->i_index = -1;    /* -1 means we are not playing anything yet */
     p_playlist->i_size = 0;
 
     p_playlist->i_mode = PLAYLIST_FORWARD;
@@ -75,7 +88,13 @@ void playlist_Init ( playlist_t * p_playlist )
     intf_Msg("intf: playlist initialized");
 }
 
-int playlist_Add( playlist_t * p_playlist, int i_pos, char * psz_item )
+/*****************************************************************************
+ * intf_PlstAdd: add an item to the playlist
+ *****************************************************************************
+ * Add an item to the playlist at position i_pos. If i_pos is PLAYLIST_END,
+ * add it at the end regardless of the playlist current size.
+ *****************************************************************************/
+int intf_PlstAdd( playlist_t * p_playlist, int i_pos, char * psz_item )
 {
     int i_index;
     playlist_item_t * p_item;
@@ -118,7 +137,13 @@ int playlist_Add( playlist_t * p_playlist, int i_pos, char * psz_item )
     return( 0 );
 }
 
-void playlist_Next( playlist_t * p_playlist )
+/*****************************************************************************
+ * intf_PlstNext: switch to next playlist item
+ *****************************************************************************
+ * Switch to the next item of the playlist. If there is no next item, the
+ * position of the resulting item is set to -1.
+ *****************************************************************************/
+void intf_PlstNext( playlist_t * p_playlist )
 {
     vlc_mutex_lock( &p_playlist->change_lock );
 
@@ -127,7 +152,13 @@ void playlist_Next( playlist_t * p_playlist )
     vlc_mutex_unlock( &p_playlist->change_lock );
 }
 
-void playlist_Prev( playlist_t * p_playlist )
+/*****************************************************************************
+ * intf_PlstPrev: switch to previous playlist item
+ *****************************************************************************
+ * Switch to the previous item of the playlist. If there is no previous
+ * item, the position of the resulting item is set to -1.
+ *****************************************************************************/
+void intf_PlstPrev( playlist_t * p_playlist )
 {
     vlc_mutex_lock( &p_playlist->change_lock );
     p_playlist->i_mode = -p_playlist->i_mode;
@@ -138,7 +169,12 @@ void playlist_Prev( playlist_t * p_playlist )
     vlc_mutex_unlock( &p_playlist->change_lock );
 }
 
-int playlist_Delete( playlist_t * p_playlist, int i_pos )
+/*****************************************************************************
+ * intf_PlstDelete: delete an item from the playlist
+ *****************************************************************************
+ * Delete the item in the playlist with position i_pos.
+ *****************************************************************************/
+int intf_PlstDelete( playlist_t * p_playlist, int i_pos )
 {
     int i_index;
     char * psz_name;
@@ -176,13 +212,18 @@ int playlist_Delete( playlist_t * p_playlist, int i_pos )
     return( 0 );
 }
 
-void playlist_Destroy( playlist_t * p_playlist )
+/*****************************************************************************
+ * intf_PlstDestroy: destroy the playlist
+ *****************************************************************************
+ * Delete all items in the playlist and free the playlist structure.
+ *****************************************************************************/
+void intf_PlstDestroy( playlist_t * p_playlist )
 {
     int i_index;
 
     for( i_index = p_playlist->i_size - 1; p_playlist->i_size; i_index-- )
     {
-        playlist_Delete( p_playlist, i_index );
+        intf_PlstDelete( p_playlist, i_index );
     }
 
     vlc_mutex_destroy( &p_playlist->change_lock );
@@ -197,6 +238,16 @@ void playlist_Destroy( playlist_t * p_playlist )
     intf_Msg("intf: playlist destroyed");
 }
 
+/*****************************************************************************
+ * Following functions are local
+ *****************************************************************************/
+
+/*****************************************************************************
+ * NextItem: select next playlist item
+ *****************************************************************************
+ * This function copies the next playlist item to the current structure,
+ * depending on the playlist browsing mode.
+ *****************************************************************************/
 static void NextItem( playlist_t * p_playlist )
 {
     if( !p_playlist->i_size )

src/interface/main.c

@@ -236,14 +236,14 @@ int main( int i_argc, char *ppsz_argv[], char *ppsz_env[] )
     /*
      * Initialize playlist and get commandline files
      */
-    p_main->p_playlist = playlist_Create( );
+    p_main->p_playlist = intf_PlstCreate( );
     if( !p_main->p_playlist )
     {
         intf_ErrMsg( "playlist error: playlist initialization failed" );
         intf_MsgDestroy();
         return( errno );
     }
-    playlist_Init( p_main->p_playlist );
+    intf_PlstInit( p_main->p_playlist );
 
     /*
      * Read configuration
@@ -261,7 +261,7 @@ int main( int i_argc, char *ppsz_argv[], char *ppsz_env[] )
     if( !p_main->p_bank )
     {
         intf_ErrMsg( "plugin error: plugin bank initialization failed" );
-        playlist_Destroy( p_main->p_playlist );
+        intf_PlstDestroy( p_main->p_playlist );
         intf_MsgDestroy();
         return( errno );
     }
@@ -275,7 +275,7 @@ int main( int i_argc, char *ppsz_argv[], char *ppsz_env[] )
     {
         intf_ErrMsg( "module error: module bank initialization failed" );
         bank_Destroy( p_main->p_bank );
-        playlist_Destroy( p_main->p_playlist );
+        intf_PlstDestroy( p_main->p_playlist );
         intf_MsgDestroy();
         return( errno );
     }
@@ -362,7 +362,7 @@ int main( int i_argc, char *ppsz_argv[], char *ppsz_env[] )
     /*
      * Free playlist
      */
-    playlist_Destroy( p_main->p_playlist );
+    intf_PlstDestroy( p_main->p_playlist );
 
 #ifdef SYS_BEOS
     /*
@@ -648,7 +648,7 @@ static int GetConfiguration( int i_argc, char *ppsz_argv[], char *ppsz_env[] )
     /* We assume that the remaining parameters are filenames */
     for( i_opt = optind; i_opt < i_argc; i_opt++ )
     {
-        playlist_Add( p_main->p_playlist, PLAYLIST_END, ppsz_argv[ i_opt ] );
+        intf_PlstAdd( p_main->p_playlist, PLAYLIST_END, ppsz_argv[ i_opt ] );
     }
 
     return( 0 );