updated doxygen stuff to generate sane user documentation (work in progress)

diff --git a/Doxyfile b/Doxyfile
index d8f1d82ac8533554baa44b07bc2d4328a71fe384..ac2eb151acdca2304c90ffd1fae61b549ac93b4c 100644 (file)
--- a/Doxyfile
+++ b/Doxyfile
@@ -67,7 +67,7 @@ GENERATE_DEPRECATEDLIST= YES
 ENABLED_SECTIONS       = 
 MAX_INITIALIZER_LINES  = 30
 SHOW_USED_FILES        = YES
-SHOW_DIRECTORIES       = NO
+SHOW_DIRECTORIES       = YES
 FILE_VERSION_FILTER    = 
 #---------------------------------------------------------------------------
 # configuration options related to warning and progress messages
@@ -83,15 +83,17 @@ WARN_LOGFILE           =
 # configuration options related to the input files
 #---------------------------------------------------------------------------
 INPUT                  = doc/src \
-                         src \
                          include \
-                         test
+                         examples #\          
+#                         src \
+#                         test \
+#                         qa
 FILE_PATTERNS          = *.h \
                          *.c \
                          *.cpp \
                          *.dox
 RECURSIVE              = YES
-EXCLUDE                = 
+EXCLUDE                = src/hostapi/wasapi/mingw-include
 EXCLUDE_SYMLINKS       = NO
 EXCLUDE_PATTERNS       = 
 EXAMPLE_PATH           = 
@@ -104,7 +106,7 @@ FILTER_SOURCE_FILES    = NO
 #---------------------------------------------------------------------------
 # configuration options related to source browsing
 #---------------------------------------------------------------------------
-SOURCE_BROWSER         = NO
+SOURCE_BROWSER         = YES
 INLINE_SOURCES         = NO
 STRIP_CODE_COMMENTS    = YES
 REFERENCED_BY_RELATION = YES

diff --git a/doc/src/license.dox b/doc/src/license.dox
index 93441074736faefbec158e046b754502c0ee40a0..31724b6980b9a24a208e9879a591aec88a080d25 100644 (file)
--- a/doc/src/license.dox
+++ b/doc/src/license.dox
@@ -1,7 +1,7 @@
 /** @page License PortAudio License\r
 \r
 PortAudio Portable Real-Time Audio Library <br>\r
-Copyright (c) 1999-2006 Ross Bencina, Phil Burk\r
+Copyright (c) 1999-2011 Ross Bencina, Phil Burk\r
 \r
 \r
 \r

diff --git a/doc/src/mainpage.dox b/doc/src/mainpage.dox
index 516403cf00a381b5400b1ee43e6732cc8d85d288..c1b2b3578f54ec0b26f880b10ce7e9e8ab90a6c5 100644 (file)
--- a/doc/src/mainpage.dox
+++ b/doc/src/mainpage.dox
@@ -1,35 +1,60 @@
 /* doxygen index page */\r
 /** @mainpage\r
 \r
+@section overview Overview\r
+\r
 PortAudio is a cross-platform, open-source C language library for real-time audio input and output. The library provides functions that allow your software to acquire and output real-time audio streams from your computer's hardware audio interfaces. It is designed to simplify writing cross-platform audio applications, and also to simplify the development of audio software in general by hiding the complexities of dealing directly with each native audio API. PortAudio is used to implement sound recording, editing and mixing applications, software synthesizers, effects processors, music players, internet telephony applications, software defined radios and more. Supported platforms include MS Windows, Mac OS X and Linux. Third-party language bindings make it possible to call PortAudio from other programming languages including C++, C#, Python, PureBasic, FreePascal and Lazarus.\r
 \r
-See the PortAudio website for further information http://www.portaudio.com\r
 \r
-Read the @ref api_overview for a top-down view of the PortAudio API, its capabilities, functions and data structures. The documentation for PortAudio's main header file portaudio.h details the individual data types and functions that make up the API.\r
+@section start_here Start here\r
 \r
-To get started writing code check out the tutorials on the PortAudio Wiki:\r
-http://www.portaudio.com/trac/wiki/TutorialDir/TutorialStart\r
+- @ref api_overview<br>\r
+A top-down view of the PortAudio API, its capabilities, functions and data structures\r
 \r
-This documentation covers the current API version: PortAudio V19, API version 2.0. API 2.0 differs in a number of ways from previous versions (most often encountered in PortAudio V18), please consult the enhancement proposals for details of what was added/changed for V19:\r
-http://www.portaudio.com/docs/proposals/index.html\r
+- <a href="http://www.portaudio.com/trac/wiki/TutorialDir/TutorialStart">PortAudio tutorials</a><br>\r
+Get started writing code with PortAudio tutorials\r
+\r
+- @ref examples_src "Examples"<br>\r
+Simple example programs demonstrating PortAudio usage\r
+\r
+- @ref License<br>\r
+PortAudio is licenced under the MIT Expat open source licence. We make a non-binding request for you to contribute your changes back to the project.\r
+\r
+\r
+@section reference API Reference\r
+\r
+- portaudio.h Portable API<br>\r
+Detailed documentation for each portable API function and data type\r
 \r
+- @ref public_header "Host API specific extensions"<br>\r
+Documentation for non-portable platform-specific host API extensions\r
 \r
-You might also be interested in:\r
 \r
-- @ref srcguide\r
+@section resources Resources\r
 \r
-- The @ref License\r
+- <a href="http://www.portaudio.com">The PortAudio website</a>\r
 \r
-- Our mailing list for users and developers:\r
-http://music.columbia.edu/mailman/listinfo/portaudio/\r
+- <a href="http://music.columbia.edu/mailman/listinfo/portaudio/">Our mailing list for users and developers</a><br>\r
 \r
-- Our issue tracking system:\r
-http://www.portaudio.com/trac\r
+- <a href="http://www.portaudio.com/trac">The PortAudio wiki</a>\r
 \r
-- Coding guidelines:\r
-http://www.portaudio.com/docs/proposals/014-StyleGuide.html\r
 \r
+@section developer_resources Developer resources\r
 \r
-If you're interested in helping out with PortAudio development we're more than happy for you to be involved. Just drop by the PortAudio mailing list and ask how you can help.\r
+\if INTERNAL\r
+- @ref srcguide \r
+\endif\r
+\r
+- <a href="http://www.portaudio.com/trac">Our Trac wiki and issue tracking system</a>\r
+\r
+- <a href="http://www.portaudio.com/docs/proposals/014-StyleGuide.html">Coding guidelines</a>\r
+\r
+If you're interested in helping out with PortAudio development we're more than happy for you to be involved. Just drop by the PortAudio mailing list and ask how you can help. Or <a href="http://www.portaudio.com/trac/report/3">check out the starter tickets in Trac</a>.\r
+\r
+\r
+@section older_api_versions Older API versions\r
+\r
+This documentation covers the current API version: PortAudio V19, API version 2.0. API 2.0 differs in a number of ways from previous versions (most often encountered in PortAudio V18), please consult the enhancement proposals for details of what was added/changed for V19:\r
+http://www.portaudio.com/docs/proposals/index.html\r
 \r
 */
\ No newline at end of file

diff --git a/doc/src/srcguide.dox b/doc/src/srcguide.dox
index 36ec2ffe3b2b15ee33de77af95f6dd3bc83bb64b..aabff5813cbffbc720a45ad20596d8e80a2f0925 100644 (file)
--- a/doc/src/srcguide.dox
+++ b/doc/src/srcguide.dox
@@ -7,33 +7,45 @@
 */\r
 \r
 /**\r
+ @internal\r
  @defgroup common_src Source code common to all implementations\r
 */\r
 \r
 /**\r
+ @internal\r
  @defgroup win_src Source code common to all Windows implementations\r
 */\r
 \r
 /**\r
+ @internal\r
  @defgroup unix_src Source code common to all Unix implementations\r
 */\r
 \r
 /**\r
+ @internal\r
  @defgroup macosx_src Source code common to all Macintosh implementations\r
 */\r
 \r
 /**\r
+ @internal\r
  @defgroup hostapi_src Source code for specific Host APIs\r
 */\r
 \r
 /**\r
- @defgroup test_src Test and example programs\r
+ @internal\r
+ @defgroup test_src Test programs\r
 */\r
 \r
 /**\r
+ @defgroup examples_src Example programs demonstrating PortAudio usage\r
+*/\r
+\r
+/**\r
+ @internal\r
  @page srcguide A guide to the PortAudio sources.\r
 \r
  - \ref public_header\r
+ - \ref example_src\r
  - \ref common_src\r
  - \ref win_src\r
  - \ref unix_src\r