Merge "Make AudioRecord and AudioTrack comments more similar"

2 files changed, 12 insertions, 3 deletions

diff --git a/include/media/AudioRecord.h b/include/media/AudioRecord.h
index d245414..8b7f20c 100644
--- a/include/media/AudioRecord.h
+++ b/include/media/AudioRecord.h
@@ -60,6 +60,7 @@ public:
         size_t      frameCount;     // number of sample frames corresponding to size;
                                     // on input it is the number of frames available,
                                     // on output is the number of frames actually drained
+                                    // (currently ignored, but will make the primary field in future)
 
         size_t      size;           // input/output in bytes == frameCount * frameSize
                                     // FIXME this is redundant with respect to frameCount,
@@ -361,7 +362,12 @@ public:
      * Input parameter 'size' is in byte units.
      * This is implemented on top of obtainBuffer/releaseBuffer. For best
      * performance use callbacks. Returns actual number of bytes read >= 0,
-     * or a negative status code.
+     * or one of the following negative status codes:
+     *      INVALID_OPERATION   AudioRecord is configured for streaming mode
+     *      BAD_VALUE           size is invalid
+     *      WOULD_BLOCK         when obtainBuffer() returns same, or
+     *                          AudioRecord was stopped during the read
+     *      or any other error code returned by IAudioRecord::start() or restoreRecord_l().
      */
             ssize_t     read(void* buffer, size_t size);
 
@@ -435,7 +441,7 @@ private:
 
     // for client callback handler
     callback_t              mCbf;               // callback handler for events, or NULL
-    void*                   mUserData;          // for client callback handler
+    void*                   mUserData;
 
     // for notification APIs
     uint32_t                mNotificationFrames; // frames between each notification callback
@@ -480,6 +486,7 @@ private:
     // multi-thread safe.
     // An exception is that a blocking ClientProxy::obtainBuffer() may be called without a lock,
     // provided that the caller also holds an extra reference to the proxy and shared memory to keep
+    // them around in case they are replaced during the obtainBuffer().
     sp<AudioRecordClientProxy> mProxy;
 
     bool                    mInOverrun;         // whether recorder is currently in overrun state
diff --git a/include/media/AudioTrack.h b/include/media/AudioTrack.h
index aa2dd4e..ddb5842 100644
--- a/include/media/AudioTrack.h
+++ b/include/media/AudioTrack.h
@@ -116,6 +116,7 @@ public:
      * Returned status (from utils/Errors.h) can be:
      *  - NO_ERROR: successful operation
      *  - NO_INIT: audio server or audio hardware not initialized
+     *  - BAD_VALUE: unsupported configuration
      */
 
     static status_t getMinFrameCount(size_t* frameCount,
@@ -682,8 +683,9 @@ protected:
         STATE_STOPPING,
     }                       mState;
 
+    // for client callback handler
     callback_t              mCbf;                   // callback handler for events, or NULL
-    void*                   mUserData;              // for client callback handler
+    void*                   mUserData;
 
     // for notification APIs
     uint32_t                mNotificationFramesReq; // requested number of frames between each