Doxygen documentation for media/base

Change-Id: I6a63bd762e9f32655baf9b40db32ababb6aa3b54

media/base/aes_encryptor.h

@@ -25,22 +25,24 @@ class AesCtrEncryptor {
   AesCtrEncryptor();
   ~AesCtrEncryptor();
 
-  // Initialize the encryptor with specified key. A random iv will be generated.
+  /// Initialize the encryptor with specified key and a random generated IV
-  // Return false if either the key or the initialization vector cannot be
+  /// of the specified size. block_offset() is reset to 0 on success.
-  // used. A valid |key| should be 16 bytes in size. A valid |iv_size| should be
+  /// @param key should be 16 bytes in size as specified in CENC spec.
-  // either 8 or 16.
+  /// @param iv_size should be either 8 or 16 as specified in CENC spec.
-  // |block_offset_| is set to 0.
+  /// @return true on successful initialization, false otherwise.
   bool InitializeWithRandomIv(const std::vector<uint8>& key, uint8 iv_size);
 
-  // Initialize the encryptor with specified key and iv. Return false if either
+  /// Initialize the encryptor with specified key and IV. block_offset() is
-  // the key or the initialization vector cannot be used. A valid |key| should
+  /// reset to 0 on success.
-  // be 16 bytes in size. A valid |iv| should be 8 bytes or 16 bytes in size.
+  /// @param key should be 16 bytes in size as specified in CENC spec.
-  // |block_offset_| is set to 0.
+  /// @param iv should be 8 bytes or 16 bytes in size as specified in CENC spec.
+  /// @return true on successful initialization, false otherwise.
   bool InitializeWithIv(const std::vector<uint8>& key,
                         const std::vector<uint8>& iv);
 
-  // Various forms of encrypt calls. |block_offset_| will be updated according
+  /// @name Various forms of encrypt calls.
-  // to input plaintext size.
+  /// block_offset() will be updated according to input plaintext size.
+  /// @{
   bool Encrypt(const uint8* plaintext,
                size_t plaintext_size,
                uint8* ciphertext);
@@ -57,6 +59,7 @@ class AesCtrEncryptor {
                    plaintext.size(),
                    reinterpret_cast<uint8*>(string_as_array(ciphertext)));
   }
+  /// @}
 
   // For AES CTR, encryption and decryption are identical.
   bool Decrypt(const uint8* ciphertext,
@@ -74,13 +77,14 @@ class AesCtrEncryptor {
     return Encrypt(ciphertext, plaintext);
   }
 
-  // Update IV for next sample. |block_offset_| is reset to 0.
+  /// Update IV for next sample. @a block_offset_ is reset to 0.
-  // As recommended in ISO/IEC FDIS 23001-7: CENC spec,
+  /// As recommended in ISO/IEC FDIS 23001-7: CENC spec,
-  //   For 64-bit IV size, new_iv = old_iv + 1;
+  ///   For 64-bit IV size, new_iv = old_iv + 1;
-  //   For 128-bit IV size, new_iv = old_iv + previous_sample_block_count.
+  ///   For 128-bit IV size, new_iv = old_iv + previous_sample_block_count.
   void UpdateIv();
 
-  // Set IV. |block_offset_| is reset to 0. Return false if |iv| is invalid.
+  /// Set IV. @a block_offset_ is reset to 0 on success.
+  /// @return true if successful, false if the input is invalid.
   bool SetIv(const std::vector<uint8>& iv);
 
   const std::vector<uint8>& iv() const { return iv_; }
@@ -109,17 +113,19 @@ class AesCbcEncryptor {
   AesCbcEncryptor();
   ~AesCbcEncryptor();
 
-  // Initialize the encryptor with specified key and iv.
+  /// Initialize the encryptor with specified key and IV.
-  // Return false if either the key or the initialization vector cannot be used.
+  /// @param key should be 128 bits or 192 bits or 256 bits in size as defined
-  // A valid |key| should be 128 bits or 192 bits or 256 bits in size as defined
+  ///        in AES spec.
-  // in AES. A valid |iv| should be 16 bytes in size.
+  /// @param iv should be 16 bytes in size.
+  /// @return true on successful initialization, false otherwise.
   bool InitializeWithIv(const std::vector<uint8>& key,
                         const std::vector<uint8>& iv);
 
-  // |plaintext| will be PKCS5 padded before being encrypted.
+  /// @param plaintext will be PKCS5 padded before being encrypted.
+  /// @param ciphertext should not be NULL.
   void Encrypt(const std::string& plaintext, std::string* ciphertext);
 
-  // Set IV. Return false if |iv| is invalid.
+  /// @return true if successful, false if the input is invalid.
   bool SetIv(const std::vector<uint8>& iv);
 
   const std::vector<uint8>& iv() const { return iv_; }
@@ -136,17 +142,20 @@ class AesCbcDecryptor {
   AesCbcDecryptor();
   ~AesCbcDecryptor();
 
-  // Initialize the decryptor with specified key and iv.
+  /// Initialize the decryptor with specified key and IV.
-  // Return false if either the key or the initialization vector cannot be used.
+  /// @param key should be 128 bits or 192 bits or 256 bits in size as defined
-  // A valid |key| should be 128 bits or 192 bits or 256 bits in size as defined
+  ///        in AES spec.
-  // in AES. A valid |iv| should be 16 bytes in size.
+  /// @param iv should be 16 bytes in size.
+  /// @return true on successful initialization, false otherwise.
   bool InitializeWithIv(const std::vector<uint8>& key,
                         const std::vector<uint8>& iv);
 
-  // We expect |ciphertext| generated with PKCS5 padding. Return false it not.
+  /// @param ciphertext is expected to be padded with PKCS5 padding.
+  /// @param plaintext should not be NULL.
+  /// @return true on success, false otherwise.
   bool Decrypt(const std::string& ciphertext, std::string* plaintext);
 
-  // Set IV. Return false if |iv| is invalid.
+  /// @return true if successful, false if the input is invalid.
   bool SetIv(const std::vector<uint8>& iv);
 
   const std::vector<uint8>& iv() const { return iv_; }

media/base/audio_stream_info.h

@@ -32,10 +32,10 @@ enum AudioCodec {
   kNumAudioCodec
 };
 
+/// Holds audio stream information.
 class AudioStreamInfo : public StreamInfo {
  public:
-  // Constructs an initialized object. It is acceptable to pass in NULL for
+  /// Construct an initialized audio stream info object.
-  // |extra_data|, otherwise the memory is copied.
   AudioStreamInfo(int track_id,
                   uint32 time_scale,
                   uint64 duration,
@@ -49,12 +49,11 @@ class AudioStreamInfo : public StreamInfo {
                   size_t extra_data_size,
                   bool is_encrypted);
 
-  // Returns true if this object has appropriate configuration values, false
+  /// @name StreamInfo implementation overrides.
-  // otherwise.
+  /// @{
   virtual bool IsValidConfig() const OVERRIDE;
-
-  // Returns a human-readable string describing |*this|.
   virtual std::string ToString() const OVERRIDE;
+  /// @}
 
   AudioCodec codec() const { return codec_; }
   uint8 sample_bits() const { return sample_bits_; }
@@ -65,7 +64,8 @@ class AudioStreamInfo : public StreamInfo {
     return static_cast<uint32>(num_channels_) * sample_bits_ / 8;
   }
 
-  // Returns the codec string. The second parameter is only used by AAC Codec.
+  /// @param audio_object_type is only used by AAC Codec, ignored otherwise.
+  /// @return The codec string.
   static std::string GetCodecString(AudioCodec codec, uint8 audio_object_type);
 
  private:

media/base/bit_reader.h

@@ -12,22 +12,24 @@
 
 namespace media {
 
-// A class to read bit streams.
+/// A class to read bit streams.
 class BitReader {
  public:
-  // Initialize the reader to start reading at |data|, |size| being size
+  /// Initialize the BitReader object to read a data buffer.
-  // of |data| in bytes.
+  /// @param data points to the beginning of the buffer.
+  /// @param size is the buffer size in bytes.
   BitReader(const uint8* data, off_t size);
   ~BitReader();
 
-  // Read |num_bits| next bits from stream and return in |*out|, first bit
+  /// Read a number of bits from stream.
-  // from the stream starting at |num_bits| position in |*out|.
+  /// @param num_bits specifies the number of bits to read. It cannot be larger
-  // |num_bits| cannot be larger than the bits the type can hold.
+  ///        than the number of bits the type can hold.
-  // Return false if the given number of bits cannot be read (not enough
+  /// @param[out] out stores the output. The type @b T has to be a primitive
-  // bits in the stream), true otherwise. When return false, the stream will
+  ///             integer type.
-  // enter a state where further ReadBits/SkipBits operations will always
+  /// @return false if the given number of bits cannot be read (not enough
-  // return false unless |num_bits| is 0. The type |T| has to be a primitive
+  ///         bits in the stream), true otherwise. When false is returned, the
-  // integer type.
+  ///         stream will enter a state where further ReadBits/SkipBits
+  ///         operations will always return false unless @a num_bits is 0.
   template<typename T> bool ReadBits(int num_bits, T *out) {
     DCHECK_LE(num_bits, static_cast<int>(sizeof(T) * 8));
     uint64 temp;
@@ -36,13 +38,15 @@ class BitReader {
     return ret;
   }
 
-  // Skip |num_bits| next bits from stream. Return false if the given number of
+  /// Skip a number of bits from stream.
-  // bits cannot be skipped (not enough bits in the stream), true otherwise.
+  /// @param num_bits specifies the number of bits to be skipped.
-  // When return false, the stream will enter a state where further ReadBits/
+  /// @return false if the given number of bits cannot be skipped (not enough
-  // SkipBits operations will always return false unless |num_bits| is 0.
+  ///         bits in the stream), true otherwise. When false is returned, the
+  ///         stream will enter a state where further ReadBits/SkipBits
+  ///         operations will always return false unless |num_bits| is 0.
   bool SkipBits(int num_bits);
 
-  // Returns the number of bits available for reading.
+  /// @return The number of bits available for reading.
   int bits_available() const;
 
  private:

media/base/buffer_reader.h

@@ -14,19 +14,23 @@
 
 namespace media {
 
-// A simple buffer reader implementation, which reads data of various type
+/// A simple buffer reader implementation, which reads data of various types
-// from a fixed byte array.
+/// from a fixed byte array.
 class BufferReader {
  public:
+  /// Create a BufferReader from a raw buffer.
   BufferReader(const uint8* buf, size_t size)
       : buf_(buf), size_(size), pos_(0) {}
   ~BufferReader() {}
 
+  /// @return true if there are more than @a count bytes in the stream, false
+  ///         otherwise.
   bool HasBytes(size_t count) { return pos() + count <= size(); }
 
-  // Read a value from the stream, performing endian correction, and advance
+  /// Read a value from the stream, performing endian correction, and advance
-  // the stream pointer.
+  /// the stream pointer.
-  // Return false if there are not enough bytes in the buffer.
+  /// @return false if there are not enough bytes in the buffer.
+  /// @{
   bool Read1(uint8* v) WARN_UNUSED_RESULT;
   bool Read2(uint16* v) WARN_UNUSED_RESULT;
   bool Read2s(int16* v) WARN_UNUSED_RESULT;
@@ -34,16 +38,21 @@ class BufferReader {
   bool Read4s(int32* v) WARN_UNUSED_RESULT;
   bool Read8(uint64* v) WARN_UNUSED_RESULT;
   bool Read8s(int64* v) WARN_UNUSED_RESULT;
-  // Read a N-byte integer of the corresponding signedness and store it in the
+  /// @}
-  // 8-byte return type. |num_bytes| should not be larger than 8 bytes.
+
-  // Return false if there are not enough bytes in the buffer.
+  /// Read N-byte integer of the corresponding signedness and store it in the
+  /// 8-byte return type.
+  /// @param num_bytes should not be larger than 8 bytes.
+  /// @return false if there are not enough bytes in the buffer, true otherwise.
+  /// @{
   bool ReadNBytesInto8(uint64* v, size_t num_bytes) WARN_UNUSED_RESULT;
   bool ReadNBytesInto8s(int64* v, size_t num_bytes) WARN_UNUSED_RESULT;
+  /// @}
 
   bool ReadToVector(std::vector<uint8>* t, size_t count) WARN_UNUSED_RESULT;
 
-  // Advance the stream by this many bytes.
+  /// Advance the stream by this many bytes.
-  // Return false if there are not enough bytes in the buffer.
+  /// @return false if there are not enough bytes in the buffer, true otherwise.
   bool SkipBytes(size_t num_bytes) WARN_UNUSED_RESULT;
 
   const uint8* data() const { return buf_; }

media/base/buffer_writer.h

@@ -3,9 +3,6 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file or at
 // https://developers.google.com/open-source/licenses/bsd
-//
-// A simple write buffer implementation, which appends various data types to
-// buffer.
 
 #ifndef MEDIA_BASE_BUFFER_WRITER_H_
 #define MEDIA_BASE_BUFFER_WRITER_H_
@@ -19,17 +16,21 @@ namespace media {
 
 class File;
 
+/// A simple buffer writer implementation which appends various data types to
+/// buffer.
 class BufferWriter {
  public:
   BufferWriter();
-  // Construct the object with a reserved capacity of |reserved_size_in_bytes|.
+  /// Construct the object with a reserved capacity.
-  // The value is intended for optimization and is not a hard limit. It does
+  /// @param reserved_size_in_bytes is intended for optimization and is
-  // not affect the actual size of the buffer, which is still starting from 0.
+  ///        not a hard limit. It does not affect the actual size of the buffer,
+  ///        which still starts from zero.
   explicit BufferWriter(size_t reserved_size_in_bytes);
   ~BufferWriter();
 
-  // These convenient functions append the integers (in network byte order,
+  /// These convenience functions append the integers (in network byte order,
-  // i.e. big endian) of various size and signedness to the end of the buffer.
+  /// i.e. big endian) of various size and signedness to the end of the buffer.
+  /// @{
   void AppendInt(uint8 v);
   void AppendInt(uint16 v);
   void AppendInt(uint32 v);
@@ -37,9 +38,11 @@ class BufferWriter {
   void AppendInt(int16 v);
   void AppendInt(int32 v);
   void AppendInt(int64 v);
+  /// @}
 
-  // Append the least significant |num_bytes| of |v| to buffer. |num_bytes|
+  /// Append the least significant @a num_bytes of @a v to buffer.
-  // should not be larger than sizeof(v), i.e. 8.
+  /// @param num_bytes should not be larger than sizeof(@a v), i.e. 8 on a
+  ///        64-bit system.
   void AppendNBytes(uint64 v, size_t num_bytes);
 
   void AppendVector(const std::vector<uint8>& v);
@@ -49,11 +52,13 @@ class BufferWriter {
   void Swap(BufferWriter* buffer) { buf_.swap(buffer->buf_); }
   void Clear() { buf_.clear(); }
   size_t Size() const { return buf_.size(); }
-  // Return underlying buffer. Return NULL if the buffer is empty.
+  /// @return Underlying buffer. Behavior is undefined if the buffer size is 0.
   const uint8* Buffer() const { return vector_as_array(&buf_); }
 
-  // Write the buffer to file. |file| should not be NULL.
+  /// Write the buffer to file. The internal buffer will be cleared after
-  // Returns OK on success. The internal buffer will be cleared after writing.
+  /// writing.
+  /// @param file should not be NULL.
+  /// @return OK on success.
   Status WriteToFile(File* file);
 
  private:

media/base/byte_queue.h

@@ -10,28 +10,28 @@
 
 namespace media {
 
-// Represents a queue of bytes.
+/// Represents a queue of bytes.
-// Data is added to the end of the queue via an Push() call and removed via
+/// Data is added to the end of the queue via an Push() and removed via Pop().
-// Pop(). The contents of the queue can be observed via the Peek() method.
+/// The contents of the queue can be observed via the Peek() method. This class
-// This class manages the underlying storage of the queue and tries to minimize
+/// manages the underlying storage of the queue and tries to minimize the
-// the number of buffer copies when data is appended and removed.
+/// number of buffer copies when data is appended and removed.
 class ByteQueue {
  public:
   ByteQueue();
   ~ByteQueue();
 
-  // Reset the queue to the empty state.
+  /// Reset the queue to the empty state.
   void Reset();
 
-  // Appends new bytes onto the end of the queue.
+  /// Append new bytes to the end of the queue.
   void Push(const uint8* data, int size);
 
-  // Get a pointer to the front of the queue and the queue size.
+  /// Get a pointer to the front of the queue and the queue size.
-  // These values are only valid until the next Push() or
+  /// These values are only valid until the next Push() or Pop() call.
-  // Pop() call.
   void Peek(const uint8** data, int* size) const;
 
-  // Remove |count| bytes from the front of the queue.
+  /// Remove a number of bytes from the front of the queue.
+  /// @param count specifies number of bytes to be popped.
   void Pop(int count);
 
  private:

media/base/container_names.h

@@ -9,11 +9,8 @@
 
 namespace media {
 
-// This is the set of input container formats detected for logging purposes. Not
+/// Container formats supported by this utility function. New formats should be
-// all of these are enabled (and it varies by product). Any additions need to be
+/// added at the end of the list (before CONTAINER_MAX).
-// done at the end of the list (before CONTAINER_MAX). This list must be kept in
-// sync with the enum definition "MediaContainers" in
-// tools/metrics/histograms/histograms.xml.
 enum MediaContainerName {
   CONTAINER_UNKNOWN,          // Unknown
   CONTAINER_AAC,              // AAC (Advanced Audio Coding)
@@ -56,7 +53,7 @@ enum MediaContainerName {
   CONTAINER_MAX               // Must be last
 };
 
-// Determine the container type.
+/// Determine the container type.
 MediaContainerName DetermineContainer(const uint8* buffer, int buffer_size);
 
 }  // namespace media

media/base/decrypt_config.h

@@ -13,36 +13,36 @@
 
 namespace media {
 
-// The Common Encryption spec provides for subsample encryption, where portions
+/// The Common Encryption spec provides for subsample encryption, where portions
-// of a sample are set in cleartext. A SubsampleEntry specifies the number of
+/// of a sample are not encrypted. A SubsampleEntry specifies the number of
-// clear and encrypted bytes in each subsample. For decryption, all of the
+/// clear and encrypted bytes in each subsample. For decryption, all of the
-// encrypted bytes in a sample should be considered a single logical stream,
+/// encrypted bytes in a sample should be considered a single logical stream,
-// regardless of how they are divided into subsamples, and the clear bytes
+/// regardless of how they are divided into subsamples, and the clear bytes
-// should not be considered as part of decryption. This is logically equivalent
+/// should not be considered as part of decryption. This is logically equivalent
-// to concatenating all 'cypher_bytes' portions of subsamples, decrypting that
+/// to concatenating all @a cypher_bytes portions of subsamples, decrypting that
-// result, and then copying each byte from the decrypted block over the
+/// result, and then copying each byte from the decrypted block over the
-// position of the corresponding encrypted byte.
+/// corresponding encrypted byte.
 struct SubsampleEntry {
   uint16 clear_bytes;
   uint32 cypher_bytes;
 };
 
-// Contains all information that a decryptor needs to decrypt a media sample.
+/// Contains all the information that a decryptor needs to decrypt a media
+/// sample.
 class DecryptConfig {
  public:
-  // Keys are always 128 bits.
+  /// Keys are always 128 bits.
   static const size_t kDecryptionKeySize = 16;
 
-  // |key_id| is the ID that references the decryption key for this sample.
+  /// @param key_id is the ID that references the decryption key.
-  // |iv| is the initialization vector defined by the encrypted format.
+  /// @param iv is the initialization vector defined by the encryptor.
-  // |data_offset| is the amount of data that should be discarded from the
+  /// @param data_offset is the amount of data that should be discarded from
-  //   head of the sample buffer before applying subsample information. A
+  ///        the head of the sample buffer before applying subsample
-  //   decrypted buffer will be shorter than an encrypted buffer by this amount.
+  ///        information. A decrypted buffer will be shorter than an encrypted
-  // |subsamples| defines the clear and encrypted portions of the sample as
+  ///        buffer by this amount.
-  //   described above. A decrypted buffer will be equal in size to the sum
+  /// @param subsamples defines the clear and encrypted portions of the sample
-  //   of the subsample sizes.
+  ///        as described in SubsampleEntry. A decrypted buffer will be equal
-  //
+  ///        in size to the sum of the subsample sizes.
-  // |data_offset| is applied before |subsamples|.
   DecryptConfig(const std::string& key_id,
                 const std::string& iv,
                 const int data_offset,

media/base/decryptor_source.h

@@ -3,8 +3,6 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file or at
 // https://developers.google.com/open-source/licenses/bsd
-//
-// DecryptorSource is responsible for decryption key acquisition.
 
 #ifndef MEDIA_BASE_DECRYPTOR_SOURCE_H_
 #define MEDIA_BASE_DECRYPTOR_SOURCE_H_
@@ -15,11 +13,17 @@
 
 namespace media {
 
+/// DecryptorSource is responsible for decryption key acquisition.
 class DecryptorSource {
  public:
   DecryptorSource() {}
   virtual ~DecryptorSource() {}
 
+  /// NeedKey event handler.
+  /// @param container indicates the container format.
+  /// @param init_data specifies container dependent initialization data that
+  ///        is used to initialize the decryption key.
+  /// @return OK on success, an adequate status on error.
   virtual Status OnNeedKey(MediaContainerName container,
                            const std::string& init_data) = 0;
 
@@ -27,6 +31,6 @@ class DecryptorSource {
   DISALLOW_COPY_AND_ASSIGN(DecryptorSource);
 };
 
-}
+}  // namespace media
 
 #endif  // MEDIA_BASE_DECRYPTOR_SOURCE_H_

media/base/demuxer.h

@@ -24,30 +24,36 @@ class MediaSample;
 class MediaStream;
 class StreamInfo;
 
+/// Demuxer is responsible for extracting elementary stream samples from a
+/// media file, e.g. an ISO BMFF file.
 class Demuxer {
  public:
-  // |file_name| specifies the input source. It uses prefix matching to create
+  /// @param file_name specifies the input source. It uses prefix matching to
-  // a proper File object. The user can extend File to support their custom
+  ///        create a proper File object. The user can extend File to support
-  // File objects with its own prefix.
+  ///        a custom File object with its own prefix.
-  // decryptor_source generates decryptor(s) when init_data is available.
+  /// @param decryptor_source generates decryptor(s) from decryption
-  // Demuxer does not take over the ownership of decryptor_source.
+  ///        initialization data. It can be NULL if the media is not encrypted.
   Demuxer(const std::string& file_name, DecryptorSource* decryptor_source);
   ~Demuxer();
 
-  // Initializes corresponding MediaParser, Decryptor, instantiates
+  /// Initialize the Demuxer. Calling other public methods of this class
-  // MediaStream(s) etc.
+  /// without this method returning OK, results in an undefined behavior.
+  /// This method primes the demuxer by parsing portions of the media file to
+  /// extract stream information.
+  /// @return OK on success.
   Status Initialize();
 
-  // Drives the remuxing from demuxer side (push): Reads the file and push
+  /// Drive the remuxing from demuxer side (push). Read the file and push
-  // the Data to Muxer until Eof.
+  /// the Data to Muxer until Eof.
   Status Run();
 
-  // Reads from the source and send it to the parser.
+  /// Read from the source and send it to the parser.
   Status Parse();
 
-  // Returns the vector of streams in this Demuxer. The caller cannot add or
+  /// @return Streams in the media container being demuxed. The caller cannot
-  // remove streams from the returned vector, but the caller is safe to change
+  ///         add or remove streams from the returned vector, but the caller is
-  // the internal state of the streams in the vector through MediaStream APIs.
+  ///         allowed to change the internal state of the streams in the vector
+  ///         through MediaStream APIs.
   const std::vector<MediaStream*>& streams() { return streams_; }
 
  private:

media/base/encryptor_source.h

@@ -3,8 +3,6 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file or at
 // https://developers.google.com/open-source/licenses/bsd
-//
-// EncryptorSource is responsible for encryption key acquisition.
 
 #ifndef MEDIA_BASE_ENCRYPTOR_SOURCE_H_
 #define MEDIA_BASE_ENCRYPTOR_SOURCE_H_
@@ -19,22 +17,19 @@ namespace media {
 
 class AesCtrEncryptor;
 
+/// EncryptorSource is responsible for encryption key acquisition.
 class EncryptorSource {
  public:
   EncryptorSource();
   virtual ~EncryptorSource();
 
-  // Initialize the encryptor source. Calling other public methods of this
+  /// Initialize the encryptor source. Calling other public methods of this
-  // class without this method returning Status::OK, results in an undefined
+  /// class without this method returning OK results in an undefined behavior.
-  // behavior.
   virtual Status Initialize() = 0;
 
-  // Refresh the encryptor. NOP except for key rotation encryptor source.
+  /// Create an encryptor from this encryptor source. The encryptor will be
-  virtual void RefreshEncryptor() {}
+  /// initialized with a random IV of the default size by default. The behavior
-
+  /// can be adjusted using set_iv_size or set_iv (exclusive).
-  // Create an encryptor from this encryptor source. The encryptor will be
-  // initialized with a random IV of the default size by default. The behavior
-  // can be adjusted using set_iv_size or set_iv (exclusive).
   scoped_ptr<AesCtrEncryptor> CreateEncryptor();
 
   const std::vector<uint8>& key_id() const { return key_id_; }
@@ -43,11 +38,11 @@ class EncryptorSource {
   const std::vector<uint8>& key_system_id() const { return key_system_id_; }
   size_t iv_size() const { return iv_.empty() ? iv_size_ : iv_.size(); }
 
-  // Set IV size. The encryptor will be initialized with a random IV of the
+  /// Set IV size. The encryptor will be initialized with a random IV of the
-  // specified size. Mutally exclusive with set_iv.
+  /// specified size. Mutually exclusive with set_iv.
   void set_iv_size(size_t iv_size) { iv_size_ = iv_size; }
-  // Set IV. The encryptor will be initialized with the specified IV.
+  /// Set IV. The encryptor will be initialized with the specified IV.
-  // Mutally exclusive with set_iv_size.
+  /// Mutually exclusive with set_iv_size.
   void set_iv(std::vector<uint8>& iv) { iv_ = iv; }
 
  protected:

media/base/fake_prng.h

@@ -12,11 +12,11 @@
 namespace media {
 namespace fake_prng {
 
-// Start using fake, deterministic PRNG for OpenSSL.
+/// Start using fake, deterministic PRNG for OpenSSL.
-// Return true if successful.
+/// @return true if successful, false otherwise.
 bool StartFakePrng();
 
-// Stop using fake, deterministic PRNG for OpenSSL.
+/// Stop using fake, deterministic PRNG for OpenSSL.
 void StopFakePrng();
 
 }  // namespace fake_prng

media/base/fixed_encryptor_source.h

@@ -3,8 +3,6 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file or at
 // https://developers.google.com/open-source/licenses/bsd
-//
-// Defines a fixed encryptor source with keys provided by user.
 
 #ifndef MEDIA_BASE_FIXED_ENCRYPTOR_SOURCE_H_
 #define MEDIA_BASE_FIXED_ENCRYPTOR_SOURCE_H_
@@ -13,6 +11,7 @@
 
 namespace media {
 
+/// Defines a fixed encryptor source with keys provided by the user.
 class FixedEncryptorSource : public EncryptorSource {
  public:
   FixedEncryptorSource(const std::string& key_id_hex,
@@ -20,7 +19,7 @@ class FixedEncryptorSource : public EncryptorSource {
                        const std::string& pssh_hex);
   virtual ~FixedEncryptorSource();
 
-  // EncryptorSource implementation.
+  /// EncryptorSource implementation override.
   virtual Status Initialize() OVERRIDE;
 
  private:

media/base/http_fetcher.h

@@ -12,21 +12,24 @@
 
 namespace media {
 
+/// Defines a generic http fetcher interface.
 class HttpFetcher {
  public:
   HttpFetcher();
   virtual ~HttpFetcher();
 
-  // Fetch |response| from |url| using HTTP GET.
+  /// Fetch content using HTTP GET.
-  // |response| should not be NULL, will contain the body of the http response
+  /// @param url specifies the content URL.
-  // on success.
+  /// @param[out] response will contain the body of the http response on
-  // Return OK on success.
+  ///             success. It should not be NULL.
+  /// @return OK on success.
   virtual Status Get(const std::string& url, std::string* response) = 0;
 
-  // Fetch |response| from |url| using HTTP POST.
+  /// Fetch content using HTTP POST.
-  // |response| should not be NULL, will contain the body of the http response
+  /// @param url specifies the content URL.
-  // on success.
+  /// @param[out] response will contain the body of the http response on
-  // Return OK on success.
+  ///             success. It should not be NULL.
+  /// @return OK on success.
   virtual Status Post(const std::string& url,
                       const std::string& data,
                       std::string* response) = 0;
@@ -35,7 +38,7 @@ class HttpFetcher {
   DISALLOW_COPY_AND_ASSIGN(HttpFetcher);
 };
 
-// A simple HttpFetcher implementation using happyhttp.
+/// A simple HttpFetcher implementation using happyhttp.
 class SimpleHttpFetcher : public HttpFetcher {
  public:
   SimpleHttpFetcher();

media/base/media_parser.h

@@ -25,39 +25,38 @@ class MediaParser {
   MediaParser() {}
   virtual ~MediaParser() {}
 
-  // Indicates completion of parser initialization.
+  /// Called upon completion of parser initialization.
-  // First parameter - A vector of all the elementary streams within this file.
+  /// @param stream_info contains the stream info of all the elementary streams
-  typedef base::Callback<void(const std::vector<scoped_refptr<StreamInfo> >&)>
+  ///        within this file.
-      InitCB;
-
-  // New stream sample have been parsed.
-  // First parameter - The track id of the new sample.
-  // Second parameter - The new media sample.
-  // Return value - True indicates that the sample is accepted.
-  //                False if something was wrong with the sample and a parsing
-  //                error should be signaled.
   typedef base::Callback<
-      bool(uint32 track_id, const scoped_refptr<MediaSample>&)>
+      void(const std::vector<scoped_refptr<StreamInfo> >& stream_info)> InitCB;
+
+  /// Called when a new media sample has been parsed.
+  /// @param track_id is the track id of the new sample.
+  /// @param media_sample is the new media sample.
+  /// @return true if the sample is accepted, false if something was wrong
+  ///         with the sample and a parsing error should be signaled.
+  typedef base::Callback<
+      bool(uint32 track_id, const scoped_refptr<MediaSample>& media_sample)>
       NewSampleCB;
 
-  // A new potentially encrypted stream has been parsed.
+  /// Called when a new potentially encrypted stream has been parsed.
-  // First Parameter - Container name.
+  /// @param init_data is the initialization data associated with the stream.
-  // Second parameter - The initialization data associated with the stream.
+  /// @param init_data_size is the number of bytes of the initialization data.
-  // Third parameter - Number of bytes of the initialization data.
+  typedef base::Callback<void(MediaContainerName container_name,
-  typedef base::Callback<void(MediaContainerName, scoped_ptr<uint8[]>, int)>
+                              scoped_ptr<uint8[]> init_data,
-      NeedKeyCB;
+                              int init_data_size)> NeedKeyCB;
 
-  // Initialize the parser with necessary callbacks. Must be called before any
+  /// Initialize the parser with necessary callbacks. Must be called before any
-  // data is passed to Parse(). |init_cb| will be called once enough data has
+  /// data is passed to Parse().
-  // been parsed to determine the initial stream configurations.
+  /// @param init_cb will be called once enough data has been parsed to
+  ///        determine the initial stream configurations.
   virtual void Init(const InitCB& init_cb,
                     const NewSampleCB& new_sample_cb,
                     const NeedKeyCB& need_key_cb) = 0;
 
-  // Called when there is new data to parse.
+  /// Should be called when there is new data to parse.
-  //
+  /// @return true if successful.
-  // Returns true if the parse succeeds.
-  // NOTE: Change to return Status.
   virtual bool Parse(const uint8* buf, int size) = 0;
 
  private:

media/base/media_sample.h

@@ -20,29 +20,37 @@ namespace media {
 
 class DecryptConfig;
 
-// Holds media sample. Also includes decoder specific functionality for
+/// Class to hold a media sample.
-// decryption.
 class MediaSample : public base::RefCountedThreadSafe<MediaSample> {
  public:
-  // Create a MediaSample whose |data_| is copied from |data|.
+  /// Create a MediaSample object from input.
-  // |data| must not be NULL and |size| >= 0.
+  /// @param data points to the buffer containing the sample data.
+  ///        Must not be NULL.
+  /// @param size indicates sample size in bytes. Must not be negative.
+  /// @param is_key_frame indicates whether the sample is a key frame.
   static scoped_refptr<MediaSample> CopyFrom(const uint8* data,
                                              int size,
                                              bool is_key_frame);
 
-  // Create a MediaSample whose |data_| is copied from |data| and |side_data_|
+  /// Create a MediaSample object from input.
-  // is copied from |side_data|. Data pointers must not be NULL and sizes
+  /// @param data points to the buffer containing the sample data.
-  // must be >= 0.
+  ///        Must not be NULL.
+  /// @param side_data points to the buffer containing the additional data.
+  ///        Some containers allow additional data to be specified.
+  ///        Must not be NULL.
+  /// @param size indicates sample size in bytes. Must not be negative.
+  /// @param side_data_size indicates additional sample data size in bytes.
+  ///        Must not be negative.
+  /// @param is_key_frame indicates whether the sample is a key frame.
   static scoped_refptr<MediaSample> CopyFrom(const uint8* data,
                                              int size,
                                              const uint8* side_data,
                                              int side_data_size,
                                              bool is_key_frame);
 
-  // Create a MediaSample indicating we've reached end of stream.
+  /// Create a MediaSample indicating we've reached end of stream.
-  //
+  /// Calling any method other than end_of_stream() on the resulting buffer
-  // Calling any method other than end_of_stream() on the resulting buffer
+  /// is disallowed.
-  // is disallowed.
   static scoped_refptr<MediaSample> CreateEOSBuffer();
 
   int64 dts() const {
@@ -118,15 +126,15 @@ class MediaSample : public base::RefCountedThreadSafe<MediaSample> {
   // If there's no data in this buffer, it represents end of stream.
   bool end_of_stream() const { return data_.size() == 0; }
 
-  // Returns a human-readable string describing |*this|.
+  /// @return a human-readable string describing |*this|.
   std::string ToString() const;
 
  protected:
   friend class base::RefCountedThreadSafe<MediaSample>;
 
-  // Allocates a buffer of size |size| >= 0 and copies |data| into it.  Buffer
+  /// Create a MediaSample. Buffer will be padded and aligned as necessary.
-  // will be padded and aligned as necessary.  If |data| is NULL then |data_| is
+  /// @param data,side_data can be NULL, which indicates an empty sample.
-  // set to NULL and |buffer_size_| to 0.
+  /// @param size,side_data_size should not be negative.
   MediaSample(const uint8* data,
               int size,
               const uint8* side_data,

media/base/media_stream.h

@@ -3,8 +3,6 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file or at
 // https://developers.google.com/open-source/licenses/bsd
-//
-// MediaStream connects Demuxer to Muxer.
 
 #ifndef MEDIA_BASE_MEDIA_STREAM_H_
 #define MEDIA_BASE_MEDIA_STREAM_H_
@@ -22,34 +20,37 @@ class Muxer;
 class MediaSample;
 class StreamInfo;
 
+/// MediaStream connects Demuxer to Muxer. It is an abstraction for a media
+/// elementary stream.
 class MediaStream {
  public:
   enum MediaStreamOperation {
     kPush,
     kPull,
   };
-  // Create MediaStream from StreamInfo and Demuxer. MediaStream does not own
+  /// Create MediaStream from StreamInfo and Demuxer.
-  // demuxer.
+  /// @param demuxer cannot be NULL.
   MediaStream(scoped_refptr<StreamInfo> info, Demuxer* demuxer);
   ~MediaStream();
 
-  // Connect the stream to Muxer. MediaStream does not own muxer.
+  /// Connect the stream to Muxer.
+  /// @param muxer cannot be NULL.
   void Connect(Muxer* muxer);
 
-  // Start the stream for pushing or pulling.
+  /// Start the stream for pushing or pulling.
   Status Start(MediaStreamOperation operation);
 
-  // Push sample to Muxer (triggered by Demuxer).
+  /// Push sample to Muxer (triggered by Demuxer).
   Status PushSample(const scoped_refptr<MediaSample>& sample);
 
-  // Pull sample from Demuxer (triggered by Muxer).
+  /// Pull sample from Demuxer (triggered by Muxer).
   Status PullSample(scoped_refptr<MediaSample>* sample);
 
   Demuxer* demuxer() { return demuxer_; }
   Muxer* muxer() { return muxer_; }
   const scoped_refptr<StreamInfo> info() const;
 
-  // Returns a human-readable string describing |*this|.
+  /// @return a human-readable string describing |*this|.
   std::string ToString() const;
 
  private:

media/base/muxer.h

@@ -30,43 +30,47 @@ namespace event {
 class MuxerListener;
 }
 
+/// Muxer is responsible for taking elementary stream samples and producing
+/// media containers. An optional EncryptorSource can be provided to Muxer to
+/// generate encrypted outputs.
 class Muxer {
  public:
   explicit Muxer(const MuxerOptions& options);
   virtual ~Muxer();
 
-  // Set encryptor source. Caller retains ownership of |encryptor_source|.
+  /// Set encryptor source. Should be called before calling Initialize().
-  // Should be called before calling Initialize().
+  /// @param encryptor_source should not be NULL.
   void SetEncryptorSource(EncryptorSource* encryptor_source,
                           double clear_lead_in_seconds);
 
-  // Initialize the muxer. Must be called after connecting all the streams.
+  /// Initialize the muxer. Must be called after connecting all the streams.
   virtual Status Initialize() = 0;
 
-  // Final clean up.
+  /// Final clean up.
   virtual Status Finalize() = 0;
 
-  // Adds video/audio stream.
+  /// Add video/audio stream.
   virtual Status AddStream(MediaStream* stream);
 
-  // Adds new media sample.
+  /// Add new media sample.
   virtual Status AddSample(const MediaStream* stream,
                            scoped_refptr<MediaSample> sample) = 0;
 
-  // Drives the remuxing from muxer side (pull).
+  /// Drive the remuxing from muxer side (pull).
   virtual Status Run();
 
-  // Set a MuxerListener event handler for this object. Ownership does not
+  /// Set a MuxerListener event handler for this object.
-  // transfer.
+  /// @param muxer_listener should not be NULL.
   void SetMuxerListener(event::MuxerListener* muxer_listener);
 
   const std::vector<MediaStream*>& streams() const { return streams_; }
 
-  // Inject clock, mainly used for testing.
+  /// Inject clock, mainly used for testing.
-  // The injected clock will be used to generate the creation time-stamp and
+  /// The injected clock will be used to generate the creation time-stamp and
-  // modification time-stamp of the muxer output.
+  /// modification time-stamp of the muxer output.
-  // If no clock is injected, the code uses base::Time::Now() to generate the
+  /// If no clock is injected, the code uses base::Time::Now() to generate the
-  // time-stamps.
+  /// time-stamps.
+  /// @param clock is the Clock to be injected.
   void set_clock(base::Clock* clock) {
     clock_ = clock;
   }

media/base/muxer_options.h

@@ -11,54 +11,56 @@
 
 namespace media {
 
+/// This structure contains the list of configuration options for Muxer.
 struct MuxerOptions {
   MuxerOptions();
   ~MuxerOptions();
 
-  // Generate a single segment for each media presentation. This option
+  /// Generate a single segment for each media presentation. This option
-  // should be set for on demand profile.
+  /// should be set for on demand profile.
   bool single_segment;
 
-  // Segment duration in seconds. If single_segment is specified, this parameter
+  /// Segment duration in seconds. If single_segment is specified, this
-  // sets the duration of a subsegment; otherwise, this parameter sets the
+  /// parameter sets the duration of a subsegment; otherwise, this parameter
-  // duration of a segment. A segment can contain one to many fragments.
+  /// sets the duration of a segment. A segment can contain one or many
+  /// fragments.
   double segment_duration;
 
-  // Fragment duration in seconds. Should not be larger than the segment
+  /// Fragment duration in seconds. Should not be larger than the segment
-  // duration.
+  /// duration.
   double fragment_duration;
 
-  // Force segments to begin with stream access points. Segment duration may
+  /// Force segments to begin with stream access points. Segment duration may
-  // not be exactly what asked by segment_duration.
+  /// not be exactly what specified by segment_duration.
   bool segment_sap_aligned;
 
-  // Force fragments to begin with stream access points. Fragment duration
+  /// Force fragments to begin with stream access points. Fragment duration
-  // may not be exactly what asked by segment_duration. Setting to true implies
+  /// may not be exactly what specified by segment_duration. Setting to true
-  // that segment_sap_aligned is true as well.
+  /// implies that segment_sap_aligned is true as well.
   bool fragment_sap_aligned;
 
-  // Set to true to normalize the presentation timestamps to start from zero.
+  /// Set to true to normalize the presentation timestamp to start from zero.
   bool normalize_presentation_timestamp;
 
-  // For ISO BMFF only.
+  /// For ISO BMFF only.
-  // Set the number of subsegments in each SIDX box. If 0, a single SIDX box
+  /// Set the number of subsegments in each SIDX box. If 0, a single SIDX box
-  // is used per segment. If -1, no SIDX box is used. Otherwise, the Muxer
+  /// is used per segment. If -1, no SIDX box is used. Otherwise, the Muxer
-  // will pack N subsegments in the root SIDX of the segment, with
+  /// will pack N subsegments in the root SIDX of the segment, with
-  // segment_duration/N/fragment_duration fragments per subsegment.
+  /// segment_duration/N/fragment_duration fragments per subsegment.
   int num_subsegments_per_sidx;
 
-  // Output file name. If segment_template is not specified, the Muxer
+  /// Output file name. If segment_template is not specified, the Muxer
-  // generates this single output file with all segments concatenated;
+  /// generates this single output file with all segments concatenated;
-  // Otherwise, it specifies the init segment name.
+  /// Otherwise, it specifies the init segment name.
   std::string output_file_name;
 
-  // Specify output segment name pattern for generated segments. It can
+  /// Specify output segment name pattern for generated segments. It can
-  // furthermore be configured by using a subset of the SegmentTemplate
+  /// furthermore be configured by using a subset of the SegmentTemplate
-  // identifiers: $RepresentationID$, $Number$, $Bandwidth$ and $Time.
+  /// identifiers: $RepresentationID$, $Number$, $Bandwidth$ and $Time.
-  // Optional.
+  /// Optional.
   std::string segment_template;
 
-  // Specify the temporary file for on demand media file creation.
+  /// Specify the temporary file for on demand media file creation.
   std::string temp_file_name;
 };
 

media/base/request_signer.h

@@ -17,13 +17,14 @@ namespace media {
 class AesCbcEncryptor;
 class RsaPrivateKey;
 
-// Define an abstract signer class for signature generation.
+/// Abstract class used for signature generation.
 class RequestSigner {
  public:
   virtual ~RequestSigner();
 
-  // Generate signature for |message|. |signature| should not be NULL.
+  /// Generate signature for the input message.
-  // Return true on success.
+  /// @param signature should not be NULL.
+  /// @return true on success, false otherwise.
   virtual bool GenerateSignature(const std::string& message,
                                  std::string* signature) = 0;
 
@@ -38,17 +39,18 @@ class RequestSigner {
   DISALLOW_COPY_AND_ASSIGN(RequestSigner);
 };
 
-// AesRequestSigner uses AES-CBC signing.
+/// AesRequestSigner uses AES-CBC signing.
 class AesRequestSigner : public RequestSigner {
  public:
   virtual ~AesRequestSigner();
 
-  // Create an AesSigner object from key and iv in hex.
+  /// Create an AesSigner object from key and iv in hex.
-  // Return NULL on failure.
+  /// @return The created AesRequestSigner object on success, NULL otherwise.
   static AesRequestSigner* CreateSigner(const std::string& signer_name,
                                         const std::string& aes_key_hex,
                                         const std::string& iv_hex);
 
+  /// RequestSigner implementation override.
   virtual bool GenerateSignature(const std::string& message,
                                  std::string* signature) OVERRIDE;
 
@@ -61,16 +63,17 @@ class AesRequestSigner : public RequestSigner {
   DISALLOW_COPY_AND_ASSIGN(AesRequestSigner);
 };
 
-// RsaRequestSigner uses RSA-PSS signing.
+/// RsaRequestSigner uses RSA-PSS signing.
 class RsaRequestSigner : public RequestSigner {
  public:
   virtual ~RsaRequestSigner();
 
-  // Create an RsaSigner object using a DER encoded PKCS#1 RSAPrivateKey.
+  /// Create an RsaSigner object using a DER encoded PKCS#1 RSAPrivateKey.
-  // Return NULL on failure.
+  /// @return The created RsaRequestSigner object on success, NULL otherwise.
   static RsaRequestSigner* CreateSigner(const std::string& signer_name,
                                         const std::string& pkcs1_rsa_key);
 
+  /// RequestSigner implementation override.
   virtual bool GenerateSignature(const std::string& message,
                                  std::string* signature) OVERRIDE;
 

media/base/rsa_key.h

@@ -19,21 +19,24 @@ typedef struct rsa_st RSA;
 
 namespace media {
 
+/// Rsa private key, used for message signing and decryption.
 class RsaPrivateKey {
  public:
   ~RsaPrivateKey();
 
-  // Create an RsaPrivateKey object using a DER encoded PKCS#1 RSAPrivateKey.
+  /// Create an RsaPrivateKey object using a DER encoded PKCS#1 RSAPrivateKey.
-  // Return NULL on failure.
+  /// @return The created RsaPrivateKey object on success, NULL otherwise.
   static RsaPrivateKey* Create(const std::string& serialized_key);
 
-  // Decrypt a message using RSA-OAEP. Caller retains ownership of all
+  /// Decrypt a message using RSA-OAEP.
-  // parameters. Return true if successful, false otherwise.
+  /// @param decrypted_message must not be NULL.
+  /// @return true if successful, false otherwise.
   bool Decrypt(const std::string& encrypted_message,
                std::string* decrypted_message);
 
-  // Generate RSASSA-PSS signature. Caller retains ownership of all parameters.
+  /// Generate RSASSA-PSS signature.
-  // Return true if successful, false otherwise.
+  /// @param signature must not be NULL.
+  /// @return true if successful, false otherwise.
   bool GenerateSignature(const std::string& message, std::string* signature);
 
  private:
@@ -45,21 +48,23 @@ class RsaPrivateKey {
   DISALLOW_COPY_AND_ASSIGN(RsaPrivateKey);
 };
 
+/// Rsa public key, used for signature verification and encryption.
 class RsaPublicKey {
  public:
   ~RsaPublicKey();
 
-  // Create an RsaPublicKey object using a DER encoded PKCS#1 RSAPublicKey.
+  /// Create an RsaPublicKey object using a DER encoded PKCS#1 RSAPublicKey.
-  // Return NULL on failure.
+  /// @return The created RsaPrivateKey object on success, NULL otherwise.
   static RsaPublicKey* Create(const std::string& serialized_key);
 
-  // Encrypt a message using RSA-OAEP. Caller retains ownership of all
+  /// Encrypt a message using RSA-OAEP.
-  // parameters. Return true if successful, false otherwise.
+  /// @param encrypted_message must not be NULL.
+  /// @return true if successful, false otherwise.
   bool Encrypt(const std::string& clear_message,
                std::string* encrypted_message);
 
-  // Verify RSASSA-PSS signature. Caller retains ownership of all parameters.
+  /// Verify RSASSA-PSS signature.
-  // Return true if validation succeeds, false otherwise.
+  /// @return true if verification succeeds, false otherwise.
   bool VerifySignature(const std::string& message,
                        const std::string& signature);
 

media/base/rsa_test_data.h

@@ -15,7 +15,7 @@
 
 namespace media {
 
-// Self generated test vector to verify algorithm stability.
+/// Self generated test vector to verify algorithm stability.
 struct RsaTestSet {
   RsaTestSet();
   ~RsaTestSet();
@@ -27,7 +27,7 @@ struct RsaTestSet {
   std::string signature;
 };
 
-// Collection of test sets.
+/// Collection of test sets.
 class RsaTestData {
  public:
   RsaTestData();

media/base/status.h

@@ -15,7 +15,7 @@ namespace media {
 
 namespace error {
 
-// Error codes for the packager APIs.
+/// Error codes for the packager APIs.
 enum Code {
   // Not an error; returned on success
   OK,
@@ -65,12 +65,12 @@ enum Code {
 
 class Status {
  public:
-  // Creates a "successful" status.
+  /// Creates a "successful" status.
   Status() : error_code_(error::OK) {}
 
-  // Create a status with the specified code, and error message. If "code == 0",
+  /// Create a status with the specified code, and error message.
-  // error_message is ignored and a Status object identical to Status::OK is
+  /// If "error_code == error::OK", error_message is ignored and a Status
-  // constructed.
+  /// object identical to Status::OK is constructed.
   Status(error::Code error_code, const std::string& error_message)
       : error_code_(error_code) {
     if (!ok())
@@ -79,13 +79,15 @@ class Status {
 
   ~Status() {}
 
-  // Some pre-defined Status objects.
+  /// @name Some pre-defined Status objects.
+  /// @{
   static const Status& OK;  // Identical to 0-arg constructor.
   static const Status& UNKNOWN;
+  /// @}
 
-  // Store the specified error in this Status object.
+  /// Store the specified error in this Status object.
-  // If "error_code == error::OK", error_message is ignored and a Status object
+  /// If "error_code == error::OK", error_message is ignored and a Status
-  // identical to Status::OK is constructed.
+  /// object identical to Status::OK is constructed.
   void SetError(error::Code error_code, const std::string& error_message) {
     if (error_code == error::OK) {
       Clear();
@@ -95,26 +97,25 @@ class Status {
     }
   }
 
-  // If "ok()", stores "new_status" into *this.  If "!ok()", preserves
+  /// If "ok()", stores "new_status" into *this.  If "!ok()", preserves
-  // the current "error_code()/error_message()",
+  /// the current "error_code()/error_message()",
-  //
+  ///
-  // Convenient way of keeping track of the first error encountered.
+  /// Convenient way of keeping track of the first error encountered.
-  // Instead of:
+  /// Instead of:
-  //   if (overall_status.ok()) overall_status = new_status
+  ///   if (overall_status.ok()) overall_status = new_status
-  // Use:
+  /// Use:
-  //   overall_status.Update(new_status);
+  ///   overall_status.Update(new_status);
   void Update(const Status& new_status) {
     if (ok())
       *this = new_status;
   }
 
-  // Clear this status object to contain the OK code and no error message.
+  /// Clear this status object to contain the OK code and no error message.
   void Clear() {
     error_code_ = error::OK;
     error_message_ = "";
   }
 
-  // Accessor.
   bool ok() const { return error_code_ == error::OK; }
   error::Code error_code() const { return error_code_; }
   const std::string& error_message() const { return error_message_; }
@@ -124,11 +125,12 @@ class Status {
   }
   bool operator!=(const Status& x) const { return !(*this == x); }
 
-  // Returns true iff this has the same error_code as "x".  I.e., the two
+  /// @return true iff this has the same error_code as "x", i.e., the two
-  // Status objects are identical except possibly for the error message.
+  ///         Status objects are identical except possibly for the error
+  ///         message.
   bool Matches(const Status& x) const { return error_code_ == x.error_code(); }
 
-  // Return a combination of the error code name and message.
+  /// @return A combination of the error code name and message.
   std::string ToString() const;
 
   void Swap(Status* other) {

media/base/stream_info.h

@@ -19,6 +19,7 @@ enum StreamType {
   kStreamVideo,
 };
 
+/// Abstract class holds stream information.
 class StreamInfo : public base::RefCountedThreadSafe<StreamInfo> {
  public:
   StreamInfo(StreamType stream_type,
@@ -31,11 +32,11 @@ class StreamInfo : public base::RefCountedThreadSafe<StreamInfo> {
              size_t extra_data_size,
              bool is_encrypted);
 
-  // Returns true if this object has appropriate configuration values, false
+  /// @return true if this object has appropriate configuration values, false
-  // otherwise.
+  ///         otherwise.
   virtual bool IsValidConfig() const = 0;
 
-  // Returns a human-readable string describing |*this|.
+  /// @return A human-readable string describing the stream info.
   virtual std::string ToString() const;
 
   StreamType stream_type() const { return stream_type_; }

media/base/text_track.h

@@ -13,7 +13,7 @@
 
 namespace media {
 
-// Specifies the varieties of text tracks.
+/// Specifies the varieties of text tracks.
 enum TextKind {
   kTextSubtitles,
   kTextCaptions,

media/base/video_stream_info.h

@@ -23,10 +23,10 @@ enum VideoCodec {
   kNumVideoCodec
 };
 
+/// Holds video stream information.
 class VideoStreamInfo : public StreamInfo {
  public:
-  // Constructs an initialized object. It is acceptable to pass in NULL for
+  /// Construct an initialized video stream info object.
-  // |extra_data|, otherwise the memory is copied.
   VideoStreamInfo(int track_id,
                   uint32 time_scale,
                   uint64 duration,
@@ -40,20 +40,19 @@ class VideoStreamInfo : public StreamInfo {
                   size_t extra_data_size,
                   bool is_encrypted);
 
-  // Returns true if this object has appropriate configuration values, false
+  /// @name StreamInfo implementation overrides.
-  // otherwise.
+  /// @{
   virtual bool IsValidConfig() const OVERRIDE;
-
-  // Returns a human-readable string describing |*this|.
   virtual std::string ToString() const OVERRIDE;
+  /// @}
 
   VideoCodec codec() const { return codec_; }
   uint16 width() const { return width_; }
   uint16 height() const { return height_; }
   uint8 nalu_length_size() const { return nalu_length_size_; }
 
-  // Returns the codec string. The parameters beyond codec are only used by
+  /// @param profile,compatible_profiles,level are only used by H.264 codec.
-  // H.264 codec.
+  /// @return The codec string.
   static std::string GetCodecString(VideoCodec codec,
                                     uint8 profile,
                                     uint8 compatible_profiles,

media/base/widevine_encryptor_source.h

@@ -16,7 +16,7 @@ namespace media {
 class HttpFetcher;
 class RequestSigner;
 
-// Defines an encryptor source which talks to Widevine encryption server.
+/// Encryptor source which talks to the Widevine encryption service.
 class WidevineEncryptorSource : public EncryptorSource {
  public:
   enum TrackType {
@@ -26,21 +26,26 @@ class WidevineEncryptorSource : public EncryptorSource {
     TRACK_TYPE_AUDIO
   };
 
-  // Caller transfers the ownership of |signer|, which should not be NULL.
+  /// @param server_url is the Widevine common encryption server url.
+  /// @param content_id the unique id identify the content to be encrypted.
+  /// @param track_type is the content type, can be AUDIO, SD or HD.
+  /// @param signer must not be NULL.
   WidevineEncryptorSource(const std::string& server_url,
                           const std::string& content_id,
                           TrackType track_type,
                           scoped_ptr<RequestSigner> signer);
   virtual ~WidevineEncryptorSource();
 
-  // EncryptorSource implementation.
+  /// EncryptorSource implementation override.
   virtual Status Initialize() OVERRIDE;
 
+  /// Inject an @b HttpFetcher object, mainly used for testing.
+  /// @param http_fetcher points to the @b HttpFetcher object to be injected.
+  void set_http_fetcher(scoped_ptr<HttpFetcher> http_fetcher);
+
   static WidevineEncryptorSource::TrackType GetTrackTypeFromString(
       const std::string& track_type_string);
 
-  void set_http_fetcher(scoped_ptr<HttpFetcher> http_fetcher);
-
  private:
   // Fill |request| with necessary fields for Widevine encryption request.
   // |request| should not be NULL.