Merge branch 'rb-document-api-version' into 'master'

Document API Version Availability (e.g. `Available as of 19.5.0`).

Merged-on: https://assembla.com/code/portaudio/git/merge_requests/3881793

include/pa_win_wasapi.h

@@ -202,11 +202,13 @@ typedef struct PaWasapiJackDescription
 PaWasapiJackDescription;
 
 
-/* Stream category.
+/** Stream category.
    Note:
     - values are equal to WASAPI AUDIO_STREAM_CATEGORY enum
     - supported since Windows 8.0, noop on earler versions
     - values 1,2 are deprecated on Windows 10 and not included into enumeration
+
+ @version Available as of 19.6.0
 */
 typedef enum PaWasapiStreamCategory
 {
@@ -224,10 +226,12 @@ typedef enum PaWasapiStreamCategory
 PaWasapiStreamCategory;
 
 
-/* Stream option.
+/** Stream option.
    Note:
     - values are equal to WASAPI AUDCLNT_STREAMOPTIONS enum
     - supported since Windows 8.1, noop on earler versions
+
+ @version Available as of 19.6.0
 */
 typedef enum PaWasapiStreamOption
 {
@@ -247,7 +251,7 @@ typedef struct PaWasapiStreamInfo
 
     unsigned long flags;            /**< collection of PaWasapiFlags */
 
-    /* Support for WAVEFORMATEXTENSIBLE channel masks. If flags contains
+    /** Support for WAVEFORMATEXTENSIBLE channel masks. If flags contains
        paWinWasapiUseChannelMask this allows you to specify which speakers 
        to address in a multichannel stream. Constants for channelMask
        are specified in pa_win_waveformat.h. Will be used only if 
@@ -255,7 +259,7 @@ typedef struct PaWasapiStreamInfo
     */
     PaWinWaveFormatChannelMask channelMask;
 
-    /* Delivers raw data to callback obtained from GetBuffer() methods skipping 
+    /** Delivers raw data to callback obtained from GetBuffer() methods skipping
        internal PortAudio processing inventory completely. userData parameter will 
        be the same that was passed to Pa_OpenStream method. Will be used only if 
        paWinWasapiRedirectHostProcessor flag is specified.
@@ -263,7 +267,7 @@ typedef struct PaWasapiStreamInfo
     PaWasapiHostProcessorCallback hostProcessorOutput;
     PaWasapiHostProcessorCallback hostProcessorInput;
 
-    /* Specifies thread priority explicitly. Will be used only if paWinWasapiThreadPriority flag
+    /** Specifies thread priority explicitly. Will be used only if paWinWasapiThreadPriority flag
        is specified.
 
        Please note, if Input/Output streams are opened simultaniously (Full-Duplex mode)
@@ -272,10 +276,16 @@ typedef struct PaWasapiStreamInfo
     */
     PaWasapiThreadPriority threadPriority;
 
-    /* Stream category. */
+    /** Stream category.
+     @see PaWasapiStreamCategory
+     @version Available as of 19.6.0
+    */
     PaWasapiStreamCategory streamCategory;
 
-    /* Stream option. */
+    /** Stream option.
+     @see PaWasapiStreamOption
+     @version Available as of 19.6.0
+    */
     PaWasapiStreamOption streamOption;
 } 
 PaWasapiStreamInfo;

include/pa_win_wdmks.h

@@ -53,14 +53,20 @@ extern "C"
 {
 #endif /* __cplusplus */
 
-    /* Setup flags */
+    /** Flags to indicate valid fields in PaWinWDMKSInfo.
+     @see PaWinWDMKSInfo
+     @version Available as of 19.5.0.
+    */
     typedef enum PaWinWDMKSFlags
     {
-        /* Makes WDMKS use the supplied latency figures instead of relying on the frame size reported
+        /** Makes WDMKS use the supplied latency figures instead of relying on the frame size reported
-           by the WaveCyclic device. Use at own risk! */
+         by the WaveCyclic device. Use at own risk!
+        */
         paWinWDMKSOverrideFramesize   = (1 << 0),
 
-        /* Makes WDMKS (output stream) use the given channelMask instead of the default */
+        /** Makes WDMKS (output stream) use the given channelMask instead of the default.
+          @version Available as of 19.5.0.
+        */
         paWinWDMKSUseGivenChannelMask = (1 << 1),
 
     } PaWinWDMKSFlags;
@@ -69,11 +75,20 @@ extern "C"
         unsigned long size;             /**< sizeof(PaWinWDMKSInfo) */
         PaHostApiTypeId hostApiType;    /**< paWDMKS */
         unsigned long version;          /**< 1 */
+
+        /** Flags indicate which fields are valid.
+         @see PaWinWDMKSFlags
+         @version Available as of 19.5.0.
+        */
         unsigned long flags;
 
-        /* The number of packets to use for WaveCyclic devices, range is [2, 8]. Set to zero for default value of 2. */
+        /** The number of packets to use for WaveCyclic devices, range is [2, 8]. Set to zero for default value of 2. */
         unsigned noOfPackets;
-        /* If paWinWDMKSUseGivenChannelMask bit is set in flags, use this as channelMask instead of default */
+
+        /** If paWinWDMKSUseGivenChannelMask bit is set in flags, use this as channelMask instead of default.
+         @see PaWinWDMKSFlags
+         @version Available as of 19.5.0.
+        */
         unsigned channelMask;
     } PaWinWDMKSInfo;
 

include/portaudio.h

@@ -51,52 +51,69 @@ extern "C"
 #endif /* __cplusplus */
 
 /** Retrieve the release number of the currently running PortAudio build.
- * For example, for version "19.5.1" this will return 0x00130501.
+ For example, for version "19.5.1" this will return 0x00130501.
- */
+
+ @see paMakeVersionNumber
+*/
 int Pa_GetVersion( void );
 
 /** Retrieve a textual description of the current PortAudio build,
- * e.g. "PortAudio V19.5.0-devel, revision 1952M".
+ e.g. "PortAudio V19.5.0-devel, revision 1952M".
- * The format of the text may change in the future. Do not try to parse the
+ The format of the text may change in the future. Do not try to parse the
- * returned string.
+ returned string.
- * @deprecated use PaVersionInfo() instead
+
- */
+ @deprecated As of 19.5.0, use Pa_GetVersionInfo()->versionText instead.
+*/
 const char* Pa_GetVersionText( void );
 
 /**
- * Generate a packed integer version number in the same format used
+ Generate a packed integer version number in the same format used
- * by Pa_GetVersion(). Use this to compare a specified version number with 
+ by Pa_GetVersion(). Use this to compare a specified version number with
- * the currently running version. For example:
+ the currently running version. For example:
- *
+
- * if( Pa_GetVersion() < paMakeVersionNumber(19,5,1) ) {}
+ @code
- */
+     if( Pa_GetVersion() < paMakeVersionNumber(19,5,1) ) {}
+ @endcode
+
+ @see Pa_GetVersion, Pa_GetVersionInfo
+ @version Available as of 19.5.0.
+*/
 #define paMakeVersionNumber(major, minor, subminor) \
     (((major)&0xFF)<<16 | ((minor)&0xFF)<<8 | ((subminor)&0xFF))
 
 
 /**
- * A structure containing the components of the version numbers.
+ A structure containing PortAudio API version information.
- */
+ @see Pa_GetVersionInfo, paMakeVersionNumber
+ @version Available as of 19.5.0.
+*/
 typedef struct PaVersionInfo {
     int versionMajor;
     int versionMinor;
     int versionSubMinor;
     /**
-     * This is currently the Git revision hash but may change in the future.
+     This is currently the Git revision hash but may change in the future.
-     * The versionControlRevision is updated by running a script before compiling the library.
+     The versionControlRevision is updated by running a script before compiling the library.
-     * If the update does not occur, this value may refer to an earlier revision.
+     If the update does not occur, this value may refer to an earlier revision.
-     */
+    */
     const char *versionControlRevision;
     /** Version as a string, for example "PortAudio V19.5.0-devel, revision 1952M" */
     const char *versionText;
 } PaVersionInfo;
     
-/**
+/** Retrieve version information for the currently running PortAudio build.
- * The structure that this points to is statically allocated.
+ @return A pointer to an immutable PaVersionInfo structure.
- * Do not attempt to free it or modify it.
+
- */
+ @note This function can be called at any time. It does not require PortAudio
+ to be initialized. The structure pointed to is statically allocated. Do not
+ attempt to free it or modify it.
+
+ @see PaVersionInfo, paMakeVersionNumber
+ @version Available as of 19.5.0.
+*/
 const PaVersionInfo* Pa_GetVersionInfo();
 
+
 /** Error codes returned by PortAudio functions.
  Note that with the exception of paNoError, all PaErrorCodes are negative.
 */