[xiph-commits] r14367 - in trunk/theora: doc include/theora

[giles at svn.xiph.org]

Author: giles
Date: 2008-01-04 21:59:57 -0800 (Fri, 04 Jan 2008)
New Revision: 14367

Modified:
   trunk/theora/doc/Doxyfile.in
   trunk/theora/include/theora/codec.h
   trunk/theora/include/theora/theora.h
Log:
Add the new API to the doxygen run, and attempt to differentiate it from
the pre-1.0 api.


Modified: trunk/theora/doc/Doxyfile.in
===================================================================
--- trunk/theora/doc/Doxyfile.in	2008-01-04 21:37:25 UTC (rev 14366)
+++ trunk/theora/doc/Doxyfile.in	2008-01-05 05:59:57 UTC (rev 14367)
@@ -211,7 +211,7 @@
 # Private class members and static file members will be hidden unless 
 # the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES
 
-EXTRACT_ALL            = NO
+EXTRACT_ALL            = YES
 
 # If the EXTRACT_PRIVATE tag is set to YES all private members of a class 
 # will be included in the documentation.
@@ -416,7 +416,7 @@
 # directories like "/usr/src/myproject". Separate the files or directories 
 # with spaces.
 
-INPUT                  = @top_srcdir@/include/theora/theora.h
+INPUT                  = @top_srcdir@/include/theora
 
 # 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 

Modified: trunk/theora/include/theora/codec.h
===================================================================
--- trunk/theora/include/theora/codec.h	2008-01-04 21:37:25 UTC (rev 14366)
+++ trunk/theora/include/theora/codec.h	2008-01-05 05:59:57 UTC (rev 14367)
@@ -32,14 +32,32 @@
  *
  * \subsection Organization
  *
- * The functions documented here are actually subdivided into two separate
- *  libraries:
- * - <tt>libtheoradec</tt>, contains the decoder and shared routines.
- *   You must link to this if you use any of the functions listed in
- *    this API, i.e., those listed in \ref basefuncs and \ref decfuncs.*/
+ * The functions documented here are actually subdivided into three 
+ * separate libraries:
+ * - <tt>libtheoraenc</tt> contains the encoder interface,
+ *   described in \ref encfuncs.
+ * - <tt>libtheoradec</tt> contains the decoder interface and
+ *   routines shared with the encoder.
+ *   You must also link to this if you link to <tt>libtheoraenc</tt>.
+ *   The routines in this library are described in \ref decfuncs and 
+ *   \ref basefuncs.
+ * - <tt>libtheora</tt> contains the \ref oldfuncs.
+ *
+ * New code should link to <tt>libtheoradec</tt> and, if using encoder
+ * features, <tt>libtheoraenc</tt>. Together these two export both
+ * the standard and the legacy API, so this is all that is needed by
+ * any code. The older <tt>libtheora</tt> library is provided just for
+ * compatibility with older build configurations.
+ *
+ * In general the recommended 1.x API symbols can be distinguished
+ * by their <tt>th_</tt> or <tt>TH_</tt> namespace prefix.
+ * The older, legacy API uses <tt>theora_</tt> or <tt>OC_</tt>
+ * prefixes instead.
+ */
 
 /**\file
- * The shared <tt>libtheoradec</tt> and <tt>libtheoraenc</tt> C API.*/
+ * The shared <tt>libtheoradec</tt> and <tt>libtheoraenc</tt> C API.
+ * You don't need to include this directly.*/
 
 #if !defined(_O_THEORA_CODEC_H_)
 # define _O_THEORA_CODEC_H_ (1)

Modified: trunk/theora/include/theora/theora.h
===================================================================
--- trunk/theora/include/theora/theora.h	2008-01-04 21:37:25 UTC (rev 14366)
+++ trunk/theora/include/theora/theora.h	2008-01-05 05:59:57 UTC (rev 14367)
@@ -33,11 +33,19 @@
 ogg_buffer_state *ogg_buffer_create(void);
 #endif
 
+/** \defgroup oldfuncs Legacy pre-1.0 C API */
+/*  @{ */
+
 /** \mainpage
  * 
  * \section intro Introduction
  *
- * This is the documentation for the libtheora C API.
+ * This is the documentation for the libtheora legacy C API, declared in 
+ * the theora.h header, which describes the old interface used before
+ * the 1.0 release. This API was widely deployed for several years and
+ * remains supported, but for new code we recommend the cleaner API 
+ * declared in theoradec.h and theoraenc.h.
+ *
  * libtheora is the reference implementation for
  * <a href="http://www.theora.org/">Theora</a>, a free video codec.
  * Theora is derived from On2's VP3 codec with improved integration for
@@ -125,7 +133,7 @@
  */
 
 /** \file
- * The libtheora C API.
+ * The libtheora pre-1.0 legacy C API.
  */
 
 /**
@@ -831,6 +839,8 @@
  * \param buf_sz The size of the parameter buffer.*/
 extern int theora_control(theora_state *th,int req,void *buf,size_t buf_sz);
 
+/* @} */ /* end oldfuncs doxygen group */
+
 #ifdef __cplusplus
 }
 #endif /* __cplusplus */