moved Doxyfile to doc/ to make sam happy. Changed Doxyfile so the generated

documentation does not include information on which headers each file
includes, since this information isn't correct.

Clarified and doxygenized some of the documentation on subpictures

Doxyfile → doc/Doxyfile

@@ -23,14 +23,14 @@ PROJECT_NAME           = vlc
 # This could be handy for archiving the generated documentation or 
 # if some version control system is used.
 
-PROJECT_NUMBER         = 0.5.0
+PROJECT_NUMBER         =
 
 # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) 
 # base path where the generated documentation will be put. 
 # If a relative path is entered, it will be relative to the location 
 # where doxygen was started. If left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       = doc/doxygen
+OUTPUT_DIRECTORY       = doxygen
 
 # The OUTPUT_LANGUAGE tag is used to specify the language in which all 
 # documentation generated by doxygen is written. Doxygen will use this 
@@ -119,7 +119,7 @@ FULL_PATH_NAMES        = YES
 # only done if one of the specified strings matches the left-hand part of 
 # the path. It is allowed to use relative paths in the argument list.
 
-STRIP_FROM_PATH        = .
+STRIP_FROM_PATH        = ..
 
 # The INTERNAL_DOCS tag determines if documentation 
 # that is typed after a \internal command is included. If the tag is set 
@@ -164,7 +164,7 @@ VERBATIM_HEADERS       = YES
 # will put list of the files that are included by a file in the documentation 
 # of that file.
 
-SHOW_INCLUDE_FILES     = YES
+SHOW_INCLUDE_FILES     = NO
 
 # If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen 
 # will interpret the first line (until the first dot) of a JavaDoc-style 
@@ -316,7 +316,7 @@ WARN_LOGFILE           =
 # directories like "/usr/src/myproject". Separate the files or directories 
 # with spaces.
 
-INPUT                  = src include
+INPUT                  = ../src ../include
 
 # If the value of the INPUT tag contains directories, you can use the 
 # FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp 
@@ -383,7 +383,7 @@ IMAGE_PATH             =
 # input file. Doxygen will then use the output that the filter program writes 
 # to standard output.
 
-INPUT_FILTER           = "./toolbox --add-include"
+INPUT_FILTER           = "../toolbox --add-include"
 
 # If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using 
 # INPUT_FILTER) will be used to filter the input files when producing source 
@@ -732,7 +732,7 @@ SEARCH_INCLUDES        = YES
 # contain include files that are not input files but should be processed by 
 # the preprocessor.
 
-INCLUDE_PATH           = include include/vlc
+INCLUDE_PATH           = ../include ../include/vlc
 
 # You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard 
 # patterns (like *.h and *.hpp) to filter out the header-files in the 
@@ -842,14 +842,14 @@ TEMPLATE_RELATIONS     = YES
 # file showing the direct and indirect include dependencies of the file with 
 # other documented files.
 
-INCLUDE_GRAPH          = YES
+INCLUDE_GRAPH          = NO
 
 # If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDED_BY_GRAPH, and 
 # HAVE_DOT tags are set to YES then doxygen will generate a graph for each 
 # documented header file showing the documented files that directly or 
 # indirectly include this file.
 
-INCLUDED_BY_GRAPH      = YES
+INCLUDED_BY_GRAPH      = NO
 
 # If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen 
 # will graphical hierarchy of all classes instead of a textual one.

include/vlc_video.h

@@ -4,7 +4,7 @@
  * includes all common video types and constants.
  *****************************************************************************
  * Copyright (C) 1999, 2000 VideoLAN
- * $Id: vlc_video.h,v 1.1 2003/06/26 12:19:59 sam Exp $
+ * $Id: vlc_video.h,v 1.2 2003/07/15 18:12:05 sigmunau Exp $
  *
  * Authors: Vincent Seguin <seguin@via.ecp.fr>
  *
@@ -153,34 +153,43 @@ struct picture_heap_t
 #define V_PIXELS     p[V_PLANE].p_pixels
 #define V_PITCH      p[V_PLANE].i_pitch
 
-/*****************************************************************************
- * subpicture_t: video subtitle
- *****************************************************************************
+/**
+ * Video subtitle
+ *
  * Any subtitle destined to be displayed by a video output thread should
  * be stored in this structure from it's creation to it's effective display.
  * Subtitle type and flags should only be modified by the output thread. Note
  * that an empty subtitle MUST have its flags set to 0.
- *****************************************************************************/
+ */
 struct subpicture_t
 {
-    /* Type and flags - should NOT be modified except by the vout thread */
-    int             i_type;                                          /* type */
-    int             i_status;                                       /* flags */
-    subpicture_t *  p_next;                 /* next subtitle to be displayed */
-
-    /* Date properties */
-    mtime_t         i_start;                    /* beginning of display date */
-    mtime_t         i_stop;                           /* end of display date */
-    vlc_bool_t      b_ephemer;             /* does the subtitle have a TTL ? */
-
-    /* Display properties - these properties are only indicative and may be
+    /** \name Type and flags
+       Should NOT be modified except by the vout thread */
+    /**@{*/
+    int             i_type;                                        /**< type */
+    int             i_status;                                     /**< flags */
+    subpicture_t *  p_next;               /**< next subtitle to be displayed */
+    /**@}*/
+
+    /** \name Date properties */
+    /**@{*/
+    mtime_t         i_start;                  /**< beginning of display date */
+    mtime_t         i_stop;                         /**< end of display date */
+    vlc_bool_t      b_ephemer;     /**< If this flag is set to true
+                                      the subtitle will be displayed
+                                      untill the next one appear */
+    /**@}*/
+
+    /** \name Display properties
+     * These properties are only indicative and may be
      * changed by the video output thread, or simply ignored depending of the
      * subtitle type. */
-    int             i_x;                   /* offset from alignment position */
-    int             i_y;                   /* offset from alignment position */
-    int             i_width;                                /* picture width */
-    int             i_height;                              /* picture height */
-
+    /**@{*/
+    int             i_x;                 /**< offset from alignment position */
+    int             i_y;                 /**< offset from alignment position */
+    int             i_width;                              /**< picture width */
+    int             i_height;                            /**< picture height */
+    /**@}*/
 #if 0
     /* Additionnal properties depending of the subpicture type */
     union
@@ -198,11 +207,12 @@ struct subpicture_t
     } type;
 #endif
 
-    /* The subpicture rendering and destruction routines */
+    /** Pointer to function that renders this subtitle in a picture */
     void ( *pf_render )  ( vout_thread_t *, picture_t *, const subpicture_t * );
+    /** Pointer to function that cleans up the private data of this subtitle */
     void ( *pf_destroy ) ( subpicture_t * );
 
-    /* Private data - the subtitle plugin might want to put stuff here to
+    /** Private data - the subtitle plugin might want to put stuff here to
      * keep track of the subpicture */
     subpicture_sys_t *p_sys;                              /* subpicture data */
 };

src/video_output/vout_subpictures.c

@@ -2,7 +2,7 @@
  * vout_subpictures.c : subpicture management functions
  *****************************************************************************
  * Copyright (C) 2000 VideoLAN
- * $Id: vout_subpictures.c,v 1.20 2003/06/26 12:19:59 sam Exp $
+ * $Id: vout_subpictures.c,v 1.21 2003/07/15 18:12:05 sigmunau Exp $
  *
  * Authors: Vincent Seguin <seguin@via.ecp.fr>
  *          Samuel Hocevar <sam@zoy.org>
@@ -34,12 +34,14 @@
 #include "vlc_video.h"
 #include "video_output.h"
 
-/*****************************************************************************
- * vout_DisplaySubPicture: display a subpicture unit
- *****************************************************************************
+/**
+ * Display a subpicture unit
+ *
  * Remove the reservation flag of a subpicture, which will cause it to be
  * ready for display.
- *****************************************************************************/
+ * \param p_vout the video output this subpicture should be displayed on
+ * \param p_subpic the subpicture to display
+ */
 void  vout_DisplaySubPicture( vout_thread_t *p_vout, subpicture_t *p_subpic )
 {
     int         i_margin;
@@ -69,14 +71,17 @@ void  vout_DisplaySubPicture( vout_thread_t *p_vout, subpicture_t *p_subpic )
     p_subpic->i_status = READY_SUBPICTURE;
 }
 
-/*****************************************************************************
- * vout_CreateSubPicture: allocate a subpicture in the video output heap.
- *****************************************************************************
+/**
+ * Allocate a subpicture in the video output heap.
+ *
  * This function create a reserved subpicture in the video output heap.
  * A null pointer is returned if the function fails. This method provides an
  * already allocated zone of memory in the spu data fields. It needs locking
  * since several pictures can be created by several producers threads.
- *****************************************************************************/
+ * \param p_vout the vout in which to create the subpicture
+ * \param i_type the type of the subpicture
+ * \return NULL on error, a reserved subpicture otherwise
+ */
 subpicture_t *vout_CreateSubPicture( vout_thread_t *p_vout, int i_type )
 {
     int                 i_subpic;                        /* subpicture index */
@@ -125,14 +130,14 @@ subpicture_t *vout_CreateSubPicture( vout_thread_t *p_vout, int i_type )
     return p_subpic;
 }
 
-/*****************************************************************************
- * vout_DestroySubPicture: remove a subpicture from the heap
- *****************************************************************************
+/**
+ * Remove a subpicture from the heap
+ *
  * This function frees a previously reserved subpicture.
  * It is meant to be used when the construction of a picture aborted.
  * This function does not need locking since reserved subpictures are ignored
  * by the output thread.
- *****************************************************************************/
+ */
 void vout_DestroySubPicture( vout_thread_t *p_vout, subpicture_t *p_subpic )
 {
     /* Get lock */