From 30d08070754346cea6abd4044a341c1a9e1204d1 Mon Sep 17 00:00:00 2001
From: rossb <rossb@0f58301d-fd10-0410-b4af-bbb618454e57>
Date: Thu, 8 Sep 2011 03:34:03 +0000
Subject: [PATCH] updated doxygen stuff to generate sane user documentation
 (work in progress)

---
 Doxyfile             | 12 ++++++----
 doc/src/license.dox  |  2 +-
 doc/src/mainpage.dox | 57 +++++++++++++++++++++++++++++++-------------
 doc/src/srcguide.dox | 14 ++++++++++-
 4 files changed, 62 insertions(+), 23 deletions(-)

diff --git a/Doxyfile b/Doxyfile
index d8f1d82..ac2eb15 100644
--- 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 9344107..31724b6 100644
--- a/doc/src/license.dox
+++ b/doc/src/license.dox
@@ -1,7 +1,7 @@
 /** @page License PortAudio License
 
 PortAudio Portable Real-Time Audio Library <br>
-Copyright (c) 1999-2006 Ross Bencina, Phil Burk
+Copyright (c) 1999-2011 Ross Bencina, Phil Burk
 
 
 
diff --git a/doc/src/mainpage.dox b/doc/src/mainpage.dox
index 516403c..c1b2b35 100644
--- a/doc/src/mainpage.dox
+++ b/doc/src/mainpage.dox
@@ -1,35 +1,60 @@
 /* doxygen index page */
 /** @mainpage
 
+@section overview Overview
+
 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.
 
-See the PortAudio website for further information http://www.portaudio.com
 
-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.
+@section start_here Start here
 
-To get started writing code check out the tutorials on the PortAudio Wiki:
-http://www.portaudio.com/trac/wiki/TutorialDir/TutorialStart
+- @ref api_overview<br>
+A top-down view of the PortAudio API, its capabilities, functions and data structures
 
-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:
-http://www.portaudio.com/docs/proposals/index.html
+- <a href="http://www.portaudio.com/trac/wiki/TutorialDir/TutorialStart">PortAudio tutorials</a><br>
+Get started writing code with PortAudio tutorials
+
+- @ref examples_src "Examples"<br>
+Simple example programs demonstrating PortAudio usage
+
+- @ref License<br>
+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.
+
+
+@section reference API Reference
+
+- portaudio.h Portable API<br>
+Detailed documentation for each portable API function and data type
 
+- @ref public_header "Host API specific extensions"<br>
+Documentation for non-portable platform-specific host API extensions
 
-You might also be interested in:
 
-- @ref srcguide
+@section resources Resources
 
-- The @ref License
+- <a href="http://www.portaudio.com">The PortAudio website</a>
 
-- Our mailing list for users and developers:
-http://music.columbia.edu/mailman/listinfo/portaudio/
+- <a href="http://music.columbia.edu/mailman/listinfo/portaudio/">Our mailing list for users and developers</a><br>
 
-- Our issue tracking system:
-http://www.portaudio.com/trac
+- <a href="http://www.portaudio.com/trac">The PortAudio wiki</a>
 
-- Coding guidelines:
-http://www.portaudio.com/docs/proposals/014-StyleGuide.html
 
+@section developer_resources Developer resources
 
-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.
+\if INTERNAL
+- @ref srcguide 
+\endif
+
+- <a href="http://www.portaudio.com/trac">Our Trac wiki and issue tracking system</a>
+
+- <a href="http://www.portaudio.com/docs/proposals/014-StyleGuide.html">Coding guidelines</a>
+
+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>.
+
+
+@section older_api_versions Older API versions
+
+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:
+http://www.portaudio.com/docs/proposals/index.html
 
 */
\ No newline at end of file
diff --git a/doc/src/srcguide.dox b/doc/src/srcguide.dox
index 36ec2ff..aabff58 100644
--- a/doc/src/srcguide.dox
+++ b/doc/src/srcguide.dox
@@ -7,33 +7,45 @@
 */
 
 /**
+ @internal
  @defgroup common_src Source code common to all implementations
 */
 
 /**
+ @internal
  @defgroup win_src Source code common to all Windows implementations
 */
 
 /**
+ @internal
  @defgroup unix_src Source code common to all Unix implementations
 */
 
 /**
+ @internal
  @defgroup macosx_src Source code common to all Macintosh implementations
 */
 
 /**
+ @internal
  @defgroup hostapi_src Source code for specific Host APIs
 */
 
 /**
- @defgroup test_src Test and example programs
+ @internal
+ @defgroup test_src Test programs
 */
 
 /**
+ @defgroup examples_src Example programs demonstrating PortAudio usage
+*/
+
+/**
+ @internal
  @page srcguide A guide to the PortAudio sources.
 
  - \ref public_header
+ - \ref example_src
  - \ref common_src
  - \ref win_src
  - \ref unix_src
-- 
2.43.0