improve doc comments. Put () after function names for consistency. Fi…

…x a few typos. (#937)

include/portaudio.h

@@ -165,13 +165,13 @@ const char *Pa_GetErrorText( PaError errorCode );
 
 /** Library initialization function - call this before using PortAudio.
  This function initializes internal data structures and prepares underlying
- host APIs for use.  With the exception of Pa_GetVersion(), Pa_GetVersionText(),
+ host APIs for use. With the exception of Pa_GetVersion(), Pa_GetVersionText(),
  and Pa_GetErrorText(), this function MUST be called before using any other
  PortAudio API functions.
 
  If Pa_Initialize() is called multiple times, each successful
  call must be matched with a corresponding call to Pa_Terminate().
- Pairs of calls to Pa_Initialize()/Pa_Terminate() may overlap, and are not
+ Pairs of calls to Pa_Initialize() / Pa_Terminate() may overlap, and are not
  required to be fully nested.
 
  Note that if Pa_Initialize() returns an error code, Pa_Terminate() should
@@ -187,7 +187,7 @@ PaError Pa_Initialize( void );
 
 /** Library termination function - call this when finished using PortAudio.
  This function deallocates all resources allocated by PortAudio since it was
- initialized by a call to Pa_Initialize(). In cases where Pa_Initialise() has
+ initialized by a call to Pa_Initialize(). In cases where Pa_Initialize() has
  been called multiple times, each call must be matched with a corresponding call
  to Pa_Terminate(). The final matching call to Pa_Terminate() will automatically
  close any PortAudio streams that are still open.
@@ -467,10 +467,10 @@ typedef double PaTime;
 
 /** A type used to specify one or more sample formats. Each value indicates
  a possible format for sound data passed to and from the stream callback,
- Pa_ReadStream and Pa_WriteStream.
+ Pa_ReadStream() and Pa_WriteStream().
 
  The standard formats paFloat32, paInt16, paInt32, paInt24, paInt8
- and aUInt8 are usually implemented by all implementations.
+ and paUInt8 are usually implemented by all implementations.
 
  The floating point representation (paFloat32) uses +1.0 and -1.0 as the
  maximum and minimum respectively.
@@ -562,7 +562,7 @@ typedef struct PaStreamParameters
     int channelCount;
 
     /** The sample format of the buffer provided to the stream callback,
-     a_ReadStream() or Pa_WriteStream(). It may be any of the formats described
+     Pa_ReadStream() or Pa_WriteStream(). It may be any of the formats described
      by the PaSampleFormat enumeration.
     */
     PaSampleFormat sampleFormat;
@@ -590,7 +590,7 @@ typedef struct PaStreamParameters
 } PaStreamParameters;
 
 
-/** Return code for Pa_IsFormatSupported indicating success. */
+/** Return code for Pa_IsFormatSupported() indicating success. */
 #define paFormatIsSupported (0)
 
 /** Determine whether it would be possible to open a stream with the specified
@@ -607,7 +607,7 @@ typedef struct PaStreamParameters
  input-only streams.
 
  @param sampleRate The required sampleRate. For full-duplex streams it is the
- sample rate for both input and output
+ sample rate for both input and output.
 
  @return Returns 0 if the format is supported, and an error code indicating why
  the format is not supported otherwise. The constant paFormatIsSupported is
@@ -652,7 +652,7 @@ typedef void PaStream;
 
 
 /** Flags used to control the behavior of a stream. They are passed as
- parameters to Pa_OpenStream or Pa_OpenDefaultStream. Multiple flags may be
+ parameters to Pa_OpenStream() or Pa_OpenDefaultStream(). Multiple flags may be
  ORed together.
 
  @see Pa_OpenStream, Pa_OpenDefaultStream
@@ -679,7 +679,7 @@ typedef unsigned long PaStreamFlags;
  only valid for full duplex callback streams and only when used in combination
  with the paFramesPerBufferUnspecified (0) framesPerBuffer parameter. Using
  this flag incorrectly results in a paInvalidFlag error being returned from
- Pa_OpenStream and Pa_OpenDefaultStream.
+ Pa_OpenStream() and Pa_OpenDefaultStream().
 
  @see PaStreamFlags, paFramesPerBufferUnspecified
 */
@@ -882,10 +882,10 @@ typedef int PaStreamCallback(
  @param streamCallback A pointer to a client supplied function that is responsible
  for processing and filling input and output buffers. If this parameter is NULL
  the stream will be opened in 'blocking read/write' mode. In blocking mode,
- the client can receive sample data using Pa_ReadStream and write sample data
- using Pa_WriteStream, the number of samples that may be read or written
- without blocking is returned by Pa_GetStreamReadAvailable and
- Pa_GetStreamWriteAvailable respectively.
+ the client can receive sample data using Pa_ReadStream() and write sample data
+ using Pa_WriteStream(), the number of samples that may be read or written
+ without blocking is returned by Pa_GetStreamReadAvailable() and
+ Pa_GetStreamWriteAvailable() respectively.
 
  @param userData A client supplied pointer which is passed to the stream callback
  function. It could for example, contain a pointer to instance data necessary
@@ -918,7 +918,7 @@ PaError Pa_OpenStream( PaStream** stream,
  a pointer to the newly opened stream.
 
  @param numInputChannels  The number of channels of sound that will be supplied
- to the stream callback or returned by Pa_ReadStream. It can range from 1 to
+ to the stream callback or returned by Pa_ReadStream(). It can range from 1 to
  the value of maxInputChannels in the PaDeviceInfo record for the default input
  device. If 0 the stream is opened as an output-only stream.
 
@@ -928,7 +928,7 @@ PaError Pa_OpenStream( PaStream** stream,
  If 0 the stream is opened as an input-only stream.
 
  @param sampleFormat The sample format of both the input and output buffers
- provided to the callback or passed to and from Pa_ReadStream and Pa_WriteStream.
+ provided to the callback or passed to and from Pa_ReadStream() and Pa_WriteStream().
  sampleFormat may be any of the formats described by the PaSampleFormat
  enumeration.
 
@@ -958,11 +958,11 @@ PaError Pa_CloseStream( PaStream *stream );
 
 
 /** Functions of type PaStreamFinishedCallback are implemented by PortAudio
- clients. They can be registered with a stream using the Pa_SetStreamFinishedCallback
+ clients. They can be registered with a stream using the Pa_SetStreamFinishedCallback()
  function. Once registered they are called when the stream becomes inactive
  (ie once a call to Pa_StopStream() will not block).
  A stream will become inactive after the stream callback returns non-zero,
- or when Pa_StopStream or Pa_AbortStream is called. For a stream providing audio
+ or when Pa_StopStream() or Pa_AbortStream() is called. For a stream providing audio
  output, if the stream callback returns paComplete, or Pa_StopStream() is called,
  the stream finished callback will not be called until all generated sample data
  has been played.
@@ -1014,7 +1014,7 @@ PaError Pa_AbortStream( PaStream *stream );
 
 /** Determine whether the stream is stopped.
  A stream is considered to be stopped prior to a successful call to
- Pa_StartStream and after a successful call to Pa_StopStream or Pa_AbortStream.
+ Pa_StartStream() and after a successful call to Pa_StopStream() or Pa_AbortStream().
  If a stream callback returns a value other than paContinue the stream is NOT
  considered to be stopped.
 
@@ -1086,7 +1086,7 @@ typedef struct PaStreamInfo
  @return A pointer to an immutable PaStreamInfo structure. If the stream
  parameter is invalid, or an error is encountered, the function returns NULL.
 
- @param stream A pointer to an open stream previously created with Pa_OpenStream.
+ @param stream A pointer to an open stream previously created with Pa_OpenStream().
 
  @note PortAudio manages the memory referenced by the returned pointer,
  the client must not manipulate or free the memory. The pointer is only
@@ -1140,9 +1140,9 @@ double Pa_GetStreamCpuLoad( PaStream* stream );
 
  Reading from a stream that is stopped is not currently supported. In particular,
  it is not possible to drain the read buffer by calling Pa_ReadStream after
- calling Pa_StopStream.
+ calling Pa_StopStream().
 
- @param stream A pointer to an open stream previously created with Pa_OpenStream.
+ @param stream A pointer to an open stream previously created with Pa_OpenStream().
 
  @param buffer A pointer to a buffer of sample frames. The buffer contains
  samples in the format specified by the inputParameters->sampleFormat field
@@ -1170,9 +1170,9 @@ PaError Pa_ReadStream( PaStream* stream,
 
  Writing to a stream that is stopped is not currently supported. In particular,
  it is not possible to prefill the write buffer by calling Pa_WriteStream
- prior to calling Pa_StartStream.
+ prior to calling Pa_StartStream().
 
- @param stream A pointer to an open stream previously created with Pa_OpenStream.
+ @param stream A pointer to an open stream previously created with Pa_OpenStream().
 
  @param buffer A pointer to a buffer of sample frames. The buffer contains
  samples in the format specified by the outputParameters->sampleFormat field