Changeset 1339

Timestamp:

02/15/08 02:50:33 (6 months ago)

Author:

rossb

Message:

resolved ticket #4 deleted V19-devel-readme.txt and moved relevant information from it into doxygen comments. improved doxygen documentation. wrapped config flags in pa_trace.h with #ifndef to allow them to be overridden using compiler flags.

Location:

portaudio/branches/v19-devel

Files:

• V19-devel-readme.txt (deleted)
• doc/src/srcguide.dox (modified) (3 diffs)
• doc/utils/checkfiledocs.py (modified) (1 diff)
• src/common/pa_allocation.h (modified) (2 diffs)
• src/common/pa_converters.c (modified) (1 diff)
• src/common/pa_front.c (modified) (2 diffs)
• src/common/pa_hostapi.h (modified) (4 diffs)
• src/common/pa_skeleton.c (modified) (1 diff)
• src/common/pa_stream.c (modified) (2 diffs)
• src/common/pa_stream.h (modified) (2 diffs)
• src/common/pa_trace.c (modified) (1 diff)
• src/common/pa_trace.h (modified) (1 diff)
• src/common/pa_util.h (modified) (2 diffs)
• src/hostapi/coreaudio/pa_mac_core_blocking.c (modified) (1 diff)
• src/hostapi/coreaudio/pa_mac_core_blocking.h (modified) (1 diff)
• src/hostapi/dsound/pa_win_ds.c (modified) (1 diff)
• src/hostapi/dsound/pa_win_ds_dynlink.c (modified) (1 diff)
• src/hostapi/dsound/pa_win_ds_dynlink.h (modified) (1 diff)
• src/hostapi/wasapi/pa_win_wasapi.cpp (modified) (1 diff)
• src/hostapi/wdmks/pa_win_wdmks.c (modified) (1 diff)
• src/hostapi/wmme/pa_win_wmme.c (modified) (1 diff)
• src/os/win/pa_win_hostapis.c (modified) (2 diffs)
• src/os/win/pa_win_util.c (modified) (2 diffs)

portaudio/branches/v19-devel/doc/src/srcguide.dox

@@ -1 +1 @@
 /*
  define all of the file groups used to structure the documentation.
+*/
+
+/**
+ @defgroup public_header Public API definitions for users of PortAudio 
 */
 
@@ -20 +24 @@
 
 /**
- @defgroup hostaip_src Source code for specific Host APIs
+ @defgroup hostapi_src Source code for specific Host APIs
 */
 
@@ -30 +34 @@
  @page srcguide A guide to the PortAudio sources.
 
+ - \ref public_header
  - \ref common_src
  - \ref win_src
  - \ref unix_src
  - \ref macosx_src
- - \ref hostaip_src
+ - \ref hostapi_src
  - \ref test_src
 */

portaudio/branches/v19-devel/doc/utils/checkfiledocs.py

@@ -6 +6 @@
 paHtmlDocDirectory = os.path.join( paRootDirectory, "doc", "html" )
 
-##this script assumes that html doxygen documentation has been generated
+## Script to check documentation status
+## this script assumes that html doxygen documentation has been generated
 ##
-##it then walks the entire portaudio source tree and check that
-##- every source file (.c,.h,.cpp) has a doxygen comment block containing
+## it then walks the entire portaudio source tree and check that
+## - every source file (.c,.h,.cpp) has a doxygen comment block containing
 ##      - a @file directive
 ##      - a @brief directive
 ##      - a @ingroup directive
-##- it also checks that a corresponding html documentation file has been generated.
+## - it also checks that a corresponding html documentation file has been generated.
 ##
-##This can be used as a first-level check to make sure the documentation is in order.
+## This can be used as a first-level check to make sure the documentation is in order.
 ##
-##The idea is to get a list of which files are missing doxygen documentation.
+## The idea is to get a list of which files are missing doxygen documentation.
 
 

portaudio/branches/v19-devel/src/common/pa_allocation.h

@@ -7 +7 @@
  *
  * Based on the Open Source API proposed by Ross Bencina
- * Copyright (c) 1999-2002 Ross Bencina, Phil Burk
+ * Copyright (c) 1999-2008 Ross Bencina, Phil Burk
  *
  * Permission is hereby granted, free of charge, to any person obtaining
@@ -44 +44 @@
 
  @brief Allocation Group prototypes. An Allocation Group makes it easy to
- allocate multiple blocks of memory and free them all simultanously.
+ allocate multiple blocks of memory and free them all at once.
  
  An allocation group is useful for keeping track of multiple blocks
  of memory which are allocated at the same time (such as during initialization)
  and need to be deallocated at the same time. The allocation group maintains
- a list of allocated blocks, and can deallocate them all simultaneously which
+ a list of allocated blocks, and can free all allocations at once. This
  can be usefull for cleaning up after a partially initialized object fails.
 

portaudio/branches/v19-devel/src/common/pa_converters.c

@@ -40 +40 @@
  @ingroup common_src
 
- @brief Conversion functions implementations.
+ @brief Conversion function implementations.
  
  If the C9x function lrintf() is available, define PA_USE_C99_LRINTF to use it

portaudio/branches/v19-devel/src/common/pa_front.c

@@ -5 +5 @@
  *
  * Based on the Open Source API proposed by Ross Bencina
- * Copyright (c) 1999-2002 Ross Bencina, Phil Burk
+ * Copyright (c) 1999-2008 Ross Bencina, Phil Burk
  *
  * Permission is hereby granted, free of charge, to any person obtaining
@@ -41 +41 @@
  @ingroup common_src
 
- @brief Implements public PortAudio API, checks some errors, forwards to
- host API implementations.
+ @brief Implements PortAudio API functions defined in portaudio.h, checks 
+ some errors, delegates platform-specific behavior to host API implementations.
  
- Implements the functions defined in the PortAudio API, checks for
- some parameter and state inconsistencies and forwards API requests to
- specific Host API implementations (via the interface declared in
- pa_hostapi.h), and Streams (via the interface declared in pa_stream.h).
-
- This file handles initialization and termination of Host API
- implementations via initializers stored in the paHostApiInitializers
- global variable.
+ Implements the functions defined in the PortAudio API (portaudio.h), 
+ validates some parameters and checks for state inconsistencies before 
+ forwarding API requests to specific Host API implementations (via the 
+ interface declared in pa_hostapi.h), and Streams (via the interface 
+ declared in pa_stream.h).
+
+ This file manages initialization and termination of Host API
+ implementations via initializer functions stored in the paHostApiInitializers
+ global array (usually defined in an os-specific pa_[os]_hostapis.c file).
+
+ This file maintains a list of all open streams and closes them at Pa_Terminate().
 
  Some utility functions declared in pa_util.h are implemented in this file.

portaudio/branches/v19-devel/src/common/pa_hostapi.h

@@ -7 +7 @@
  *
  * Based on the Open Source API proposed by Ross Bencina
- * Copyright (c) 1999-2002 Ross Bencina, Phil Burk
+ * Copyright (c) 1999-2008 Ross Bencina, Phil Burk
  *
  * Permission is hereby granted, free of charge, to any person obtaining
@@ -43 +43 @@
  @ingroup common_src
 
- @brief Interface used by pa_front to virtualize functions which operate on
- host APIs.
+ @brief Interfaces and representation structures used by pa_front.c 
+ to manage and communicate with host API implementations.
 */
 
@@ -225 +225 @@
  host API.
  
+ This function should only return an error other than paNoError if it encounters 
+ an unexpected and fatal error (memory allocation error for example). In general, 
+ there may be conditions under which it returns a NULL interface pointer and also 
+ returns paNoError. For example, if the ASIO implementation detects that ASIO is 
+ not installed, it should return a NULL interface, and paNoError.
+
  @see paHostApiInitializers
 */
@@ -231 +237 @@
 
 /** paHostApiInitializers is a NULL-terminated array of host API initialization
- functions. These functions are called by pa_front to initialize the host APIs
+ functions. These functions are called by pa_front.c to initialize the host APIs
  when the client calls Pa_Initialize().
 

portaudio/branches/v19-devel/src/common/pa_skeleton.c

@@ -44 +44 @@
  @brief Skeleton implementation of support for a host API.
 
- @note This file is provided as a starting point for implementing support for
- a new host API. IMPLEMENT ME comments are used to indicate functionality
+ This file is provided as a starting point for implementing support for
+ a new host API. It provides examples of how the common code can be used.
+
+ @note IMPLEMENT ME comments are used to indicate functionality
  which much be customised for each implementation.
 */

portaudio/branches/v19-devel/src/common/pa_stream.c

@@ -2 +2 @@
  * $Id$
  * Portable Audio I/O Library
- * 
+ * stream interface
  *
  * Based on the Open Source API proposed by Ross Bencina
- * Copyright (c) 2002 Ross Bencina
+ * Copyright (c) 2008 Ross Bencina
  *
  * Permission is hereby granted, free of charge, to any person obtaining
@@ -41 +41 @@
  @ingroup common_src
 
- @brief Interface used by pa_front to virtualize functions which operate on
- streams.
+ @brief Stream interfaces, representation structures and helper functions
+ used to interface between pa_front.c host API implementations.
 */
 

portaudio/branches/v19-devel/src/common/pa_stream.h

@@ -7 +7 @@
  *
  * Based on the Open Source API proposed by Ross Bencina
- * Copyright (c) 1999-2002 Ross Bencina, Phil Burk
+ * Copyright (c) 1999-2008 Ross Bencina, Phil Burk
  *
  * Permission is hereby granted, free of charge, to any person obtaining
@@ -43 +43 @@
  @ingroup common_src
 
- @brief Interface used by pa_front to virtualize functions which operate on
- streams.
+ @brief Stream interfaces, representation structures and helper functions
+ used to interface between pa_front.c host API implementations.
 */
 

portaudio/branches/v19-devel/src/common/pa_trace.c

@@ -41 +41 @@
  @ingroup common_src
 
- @brief Event trace mechanism for debugging.
+ @brief Real-time safe event trace logging facility for debugging.
 */
 

portaudio/branches/v19-devel/src/common/pa_trace.h

@@ -43 +43 @@
  @ingroup common_src
 
- @brief Event trace mechanism for debugging.
+ @brief Real-time safe event trace logging facility for debugging.
 
- Allows data to be written to the buffer at interrupt time and dumped later.
+ Allows data to be logged to a fixed size trace buffer in a real-time
+ execution context (such as at interrupt time). Each log entry consists 
+ of a message comprising a string pointer and an int.  The trace buffer 
+ may be dumped to stdout later.
+
+ This facility is only active if PA_TRACE_REALTIME_EVENTS is set to 1,
+ otherwise the trace functions expand to no-ops.
+
+ @fn PaUtil_ResetTraceMessages
+ @brief Clear the trace buffer.
+
+ @fn PaUtil_AddTraceMessage
+ @brief Add a message to the trace buffer. A message consists of string and an int.
+ @param msg The string pointer must remain valid until PaUtil_DumpTraceMessages 
+    is called. As a result, usually only string literals should be passed as 
+    the msg parameter.
+
+ @fn PaUtil_DumpTraceMessages
+ @brief Print all messages in the trace buffer to stdout and clear the trace buffer.
 */
 
+#ifndef PA_TRACE_REALTIME_EVENTS
+#define PA_TRACE_REALTIME_EVENTS     (0)   /**< Set to 1 to enable logging using the trace functions defined below */
+#endif
 
-#define PA_TRACE_REALTIME_EVENTS     (0)   /* Keep log of various real-time events. */
-#define PA_MAX_TRACE_RECORDS      (2048)
+#ifndef PA_MAX_TRACE_RECORDS
+#define PA_MAX_TRACE_RECORDS      (2048)   /**< Maximum number of records stored in trace buffer */   
+#endif
 
 #ifdef __cplusplus

portaudio/branches/v19-devel/src/common/pa_util.h

@@ -7 +7 @@
  *
  * Based on the Open Source API proposed by Ross Bencina
- * Copyright (c) 1999-2002 Ross Bencina, Phil Burk
+ * Copyright (c) 1999-2008 Ross Bencina, Phil Burk
  *
  * Permission is hereby granted, free of charge, to any person obtaining
@@ -44 +44 @@
 
     @brief Prototypes for utility functions used by PortAudio implementations.
+
+    Some functions declared here are defined in pa_front.c while others
+    are implemented separately for each platform.
 
     @todo Document and adhere to the alignment guarantees provided by

portaudio/branches/v19-devel/src/hostapi/coreaudio/pa_mac_core_blocking.c

@@ -54 +54 @@
 /**
  @file
- @ingroup hostaip_src
+ @ingroup hostapi_src
 
  This file contains the implementation

portaudio/branches/v19-devel/src/hostapi/coreaudio/pa_mac_core_blocking.h

@@ -54 +54 @@
 /**
  @file
- @ingroup hostaip_src
+ @ingroup hostapi_src
 */
 

portaudio/branches/v19-devel/src/hostapi/dsound/pa_win_ds.c

@@ -39 +39 @@
 
 /** @file
- @ingroup hostaip_src
+ @ingroup hostapi_src
 
     @todo implement paInputOverflow callback status flag

portaudio/branches/v19-devel/src/hostapi/dsound/pa_win_ds_dynlink.c

@@ -42 +42 @@
 /**
  @file
- @ingroup hostaip_src
+ @ingroup hostapi_src
 */
 

portaudio/branches/v19-devel/src/hostapi/dsound/pa_win_ds_dynlink.h

@@ -42 +42 @@
 /**
  @file
- @ingroup hostaip_src
+ @ingroup hostapi_src
 */
 

portaudio/branches/v19-devel/src/hostapi/wasapi/pa_win_wasapi.cpp

@@ -38 +38 @@
 
 /** @file
- @ingroup hostaip_src
+ @ingroup hostapi_src
  @brief WASAPI implementation of support for a host API.
 

portaudio/branches/v19-devel/src/hostapi/wdmks/pa_win_wdmks.c

@@ -39 +39 @@
 
 /** @file
- @ingroup hostaip_src
+ @ingroup hostapi_src
  @brief Portaudio WDM-KS host API.
 

portaudio/branches/v19-devel/src/hostapi/wmme/pa_win_wmme.c

@@ -63 +63 @@
 
 /** @file
-        @ingroup hostaip_src
+        @ingroup hostapi_src
+
+    @brief Win32 host API implementation for the Windows MultiMedia Extensions (WMME) audio API.
 
         @todo Fix buffer catch up code, can sometimes get stuck (perhaps fixed now,

portaudio/branches/v19-devel/src/os/win/pa_win_hostapis.c

@@ -4 +4 @@
  *
  * Based on the Open Source API proposed by Ross Bencina
- * Copyright (c) 1999-2002 Ross Bencina, Phil Burk
+ * Copyright (c) 1999-2008 Ross Bencina, Phil Burk
  *
  * Permission is hereby granted, free of charge, to any person obtaining
@@ -40 +40 @@
  @ingroup win_src
 
-    Win32 host API initialization function table.
+    @brief Win32 host API initialization function table.
 
     @todo Consider using PA_USE_WMME etc instead of PA_NO_WMME. This is what

portaudio/branches/v19-devel/src/os/win/pa_win_util.c

@@ -5 +5 @@
  *
  * Based on the Open Source API proposed by Ross Bencina
- * Copyright (c) 1999-2000 Ross Bencina
+ * Copyright (c) 1999-2008 Ross Bencina
  *
  * Permission is hereby granted, free of charge, to any person obtaining
@@ -41 +41 @@
  @ingroup win_src
 
- Win32 platform-specific support functions.
+ @brief Win32 implementation of platform-specific PaUtil support functions.
 
     @todo Implement workaround for QueryPerformanceCounter() skipping forward