toolbox: made a --add-include that can be used by doxygen to get proper

         includes in the .h files, since they are parsed out of context by
	 doxygen
Doxyfile: misc fixes, use ./toolbox --add-include as filter for sources.
include/vlc_common.h: doxygenized VLC_COMMON_MEMBERS

With these changes, and a slightly patched version of doxygen (which you can
get here: http://www.idi.ntnu.no/~sigmunau/doxygen-vlcpatched.tgz ) you should
be able to get some useful documentation out of the vlc sources.

diff --git a/Doxyfile b/Doxyfile
index 16481566486e53cdad9b181b525a9da88e488210..c36f237f5396c59413e20a64a29a106d175ed1ac 100644 (file)
--- a/Doxyfile
+++ b/Doxyfile
@@ -112,14 +112,14 @@ INLINE_INHERITED_MEMB  = NO
 # path before files name in the file list and in the header files. If set 
 # to NO the shortest path that makes the file name unique will be used.
 
-FULL_PATH_NAMES        = NO
+FULL_PATH_NAMES        = YES
 
 # If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag 
 # can be used to strip a user defined part of the path. Stripping is 
 # 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 
@@ -172,7 +172,7 @@ SHOW_INCLUDE_FILES     = YES
 # comments  will behave just like the Qt-style comments (thus requiring an 
 # explict @brief command for a brief description.
 
-JAVADOC_AUTOBRIEF      = NO
+JAVADOC_AUTOBRIEF      = YES
 
 # If the DETAILS_AT_TOP tag is set to YES then Doxygen 
 # will output the detailed description near the top, like JavaDoc.
@@ -383,7 +383,7 @@ IMAGE_PATH             =
 # input file. Doxygen will then use the output that the filter program writes 
 # to standard output.
 
-INPUT_FILTER           = 
+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 
@@ -715,7 +715,7 @@ ENABLE_PREPROCESSING   = YES
 # compilation will be performed. Macro expansion can be done in a controlled 
 # way by setting EXPAND_ONLY_PREDEF to YES.
 
-MACRO_EXPANSION        = NO
+MACRO_EXPANSION        = YES
 
 # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES 
 # then the macro expansion is limited to the macros specified with the 
@@ -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_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 
@@ -761,7 +761,7 @@ EXPAND_AS_DEFINED      =
 # on a line and do not end with a semicolon. Such function macros are typically 
 # used for boiler-plate code, and will confuse the parser if not removed.
 
-SKIP_FUNCTION_MACROS   = YES
+SKIP_FUNCTION_MACROS   = NO
 
 #---------------------------------------------------------------------------
 # Configuration::addtions related to external references   

diff --git a/include/vlc_common.h b/include/vlc_common.h
index 463b1bb8b5deee47e355130974f46b0d6f061cec..1cf3b49c5ace5023a187829c63c06545fd16123b 100644 (file)
--- a/include/vlc_common.h
+++ b/include/vlc_common.h
@@ -3,7 +3,7 @@
  * Collection of useful common types and macros definitions
  *****************************************************************************
  * Copyright (C) 1998, 1999, 2000 VideoLAN
- * $Id: vlc_common.h,v 1.67 2003/06/05 11:52:19 gbazin Exp $
+ * $Id: vlc_common.h,v 1.68 2003/07/14 20:36:55 sigmunau Exp $
  *
  * Authors: Samuel Hocevar <sam@via.ecp.fr>
  *          Vincent Seguin <seguin@via.ecp.fr>
@@ -243,6 +243,8 @@ typedef struct picture_heap_t picture_heap_t;
 typedef struct subpicture_t subpicture_t;
 typedef struct subpicture_sys_t subpicture_sys_t;
 typedef struct vout_synchro_t vout_synchro_t;
+typedef struct text_renderer_sys_t text_renderer_sys_t;
+typedef struct text_style_t text_style_t;
 
 /* Stream output */
 typedef struct sout_instance_t sout_instance_t;
@@ -305,6 +307,10 @@ typedef int ( * vlc_callback_t ) ( vlc_object_t *,      /* variable's object */
 
 /* VLC_COMMON_MEMBERS : members common to all basic vlc objects */
 #define VLC_COMMON_MEMBERS                                                  \
+/** \name VLC_COMMON_MEMBERS                                                \
+ * these members are common for all vlc objects                             \
+ */                                                                         \
+/**@{*/                                                                     \
     int   i_object_id;                                                      \
     int   i_object_type;                                                    \
     char *psz_object_type;                                                  \
@@ -319,10 +325,10 @@ typedef int ( * vlc_callback_t ) ( vlc_object_t *,      /* variable's object */
     vlc_cond_t   object_wait;                                               \
                                                                             \
     /* Object properties */                                                 \
-    volatile vlc_bool_t b_error;                    /* set by the object */ \
-    volatile vlc_bool_t b_die;                     /* set by the outside */ \
-    volatile vlc_bool_t b_dead;                     /* set by the object */ \
-    volatile vlc_bool_t b_attached;                 /* set by the object */ \
+    volatile vlc_bool_t b_error;                  /**< set by the object */ \
+    volatile vlc_bool_t b_die;                   /**< set by the outside */ \
+    volatile vlc_bool_t b_dead;                   /**< set by the object */ \
+    volatile vlc_bool_t b_attached;               /**< set by the object */ \
                                                                             \
     /* Object variables */                                                  \
     vlc_mutex_t     var_lock;                                               \
@@ -330,19 +336,20 @@ typedef int ( * vlc_callback_t ) ( vlc_object_t *,      /* variable's object */
     variable_t *    p_vars;                                                 \
                                                                             \
     /* Stuff related to the libvlc structure */                             \
-    libvlc_t *      p_libvlc;                        /* root of all evil */ \
-    vlc_t *         p_vlc;                     /* (root of all evil) - 1 */ \
+    libvlc_t *      p_libvlc;                      /**< root of all evil */ \
+    vlc_t *         p_vlc;                   /**< (root of all evil) - 1 */ \
                                                                             \
-    volatile int    i_refcount;                           /* usage count */ \
-    vlc_object_t *  p_parent;                              /* our parent */ \
-    vlc_object_t ** pp_children;                         /* our children */ \
+    volatile int    i_refcount;                         /**< usage count */ \
+    vlc_object_t *  p_parent;                            /**< our parent */ \
+    vlc_object_t ** pp_children;                       /**< our children */ \
     volatile int    i_children;                                             \
                                                                             \
     /* Private data */                                                      \
     void *          p_private;                                              \
                                                                             \
-    /* Just a reminder so that people don't cast garbage */                 \
+    /** Just a reminder so that people don't cast garbage */                \
     int be_sure_to_add_VLC_COMMON_MEMBERS_to_struct;                        \
+/**@}*/                                                                     \
 
 /* VLC_OBJECT: attempt at doing a clever cast */
 #define VLC_OBJECT( x ) \

diff --git a/toolbox b/toolbox
index 4288840926b669b64e771ca06643b890714a8c88..cec735571f20fc51921da108ff91a91ff22287e6 100755 (executable)
--- a/toolbox
+++ b/toolbox
@@ -1,7 +1,7 @@
 #! /bin/sh
 
 ##  toolbox for the VLC media player
-##  $Id: toolbox,v 1.40 2003/07/08 16:21:00 sam Exp $
+##  $Id: toolbox,v 1.41 2003/07/14 20:36:55 sigmunau Exp $
 ##
 ##  Authors: Samuel Hocevar <sam@zoy.org>
 
@@ -81,6 +81,9 @@ case "$1" in
   --make-woody)
     action=woody
     ;;
+  --add-include)
+    action=include
+    ;;
   --help)
     help
     ;;
@@ -91,6 +94,19 @@ case "$1" in
 esac
 shift
 
+##
+##  Add includes to help doxygen
+##
+if test "${action}" = "include"
+then
+  case "$1" in
+    */vlc_common.h|*/include/vlc/*);;
+    */include/*.h) echo "#include <vlc_common.h>" ;;
+  esac
+  cat $1
+  exit 0
+fi
+
 ##
 ##  Update the CVS changelog
 ##