Doxygen doc for MPD generation classes.

Change-Id: I8d28d05395732684f8c8fc73a8a40656ffa26a74

mpd/base/content_protection_element.h

@@ -17,6 +17,8 @@
 
 namespace dash_packager {
 
+/// Structure to represent <ContentProtection> element in DASH MPD spec (ISO
+/// 23009-1:2012 MPD and Segment Formats).
 struct ContentProtectionElement {
   ContentProtectionElement();
   ~ContentProtectionElement();

mpd/base/mpd_builder.cc

@@ -105,15 +105,6 @@ AdaptationSet* MpdBuilder::AddAdaptationSet() {
   return adaptation_set.release();
 }
 
-bool MpdBuilder::WriteMpd() {
-  base::AutoLock scoped_lock(lock_);
-  std::string mpd;
-  bool result = ToStringImpl(&mpd);
-
-  // NOTE: Write to file, after interface change.
-  return result;
-}
-
 bool MpdBuilder::ToString(std::string* output) {
   base::AutoLock scoped_lock(lock_);
   return ToStringImpl(output);

mpd/base/mpd_builder.h

@@ -7,7 +7,6 @@
 // This file contains the MpdBuilder, AdaptationSet, and Representation class
 // declarations.
 // http://goo.gl/UrsSlF
-
 #ifndef MPD_BASE_MPD_BUILDER_H_
 #define MPD_BASE_MPD_BUILDER_H_
 
@@ -34,6 +33,7 @@ class XmlNode;
 
 }  // namespace xml
 
+/// This class generates DASH MPDs (Media Presentation Descriptions).
 class MpdBuilder {
  public:
   enum MpdType {
@@ -41,16 +41,23 @@ class MpdBuilder {
     kDynamic
   };
 
+  /// Constructs MpdBuilder.
+  /// @param type indicates whether the MPD should be for VOD or live content
+  ///        (kStatic for VOD profile, or kDynamic for live profile).
   explicit MpdBuilder(MpdType type);
   ~MpdBuilder();
 
+  /// Add <BaseURL> entry to the MPD.
+  /// @param base_url URL for <BaseURL> entry.
   void AddBaseUrl(const std::string& base_url);
 
-  // The returned pointer is owned by this object.
+  /// Adds <AdaptationSet> to the MPD.
+  /// @return The new adaptation set, which is owned by this instance.
   AdaptationSet* AddAdaptationSet();
 
-  // This will write to stdout until File interface is defined.
+  /// Writes the MPD to the given string.
-  bool WriteMpd();
+  /// @param[out] output is an output string where the MPD gets written.
+  /// @return true on success, false otherwise.
   bool ToString(std::string* output);
 
  private:
@@ -79,23 +86,35 @@ class MpdBuilder {
   DISALLOW_COPY_AND_ASSIGN(MpdBuilder);
 };
 
+/// AdaptationSet class provides methods to add Representations and
+/// <ContentProtection> elements to the AdaptationSet element.
 class AdaptationSet {
  public:
+  /// @param adaptation_set_id is an ID number for this AdaptationSet.
+  /// @param representation_counter is a Counter for assigning ID numbers to
+  ///                               Representation. It can not be NULL.
   AdaptationSet(uint32 adaptation_set_id,
                 base::AtomicSequenceNumber* representation_counter);
   ~AdaptationSet();
 
-  // The returned pointer is owned by this object.
+  /// Create a Representation instance using @a media_info.
+  /// @param media_info is a MediaInfo object used to initialize the returned
+  ///        Representation instance.
+  /// @return On success, returns a pointer to Representation. Otherwise returns
+  ///         NULL. The returned pointer is owned by the AdaptationSet instance.
   Representation* AddRepresentation(const MediaInfo& media_info);
 
-  // If |element| has {value, schemeIdUri} set and has
+  /// Add a ContenProtection element to the adaptation set.
-  // {“value”, “schemeIdUri”} as key for additional_attributes,
+  /// @param element contains the ContentProtection element contents.
-  // then the former is used.
+  ///        If @a element has {value, schemeIdUri} set and has
+  ///        {“value”, “schemeIdUri”} as key for @a additional_attributes,
+  ///        then the former is used.
   void AddContentProtectionElement(const ContentProtectionElement& element);
 
-  // Makes a copy of AdaptationSet xml element with its child elements, which
+  /// Makes a copy of AdaptationSet xml element with its child Representation
-  // are Representation elements. On success this returns non-NULL ScopedXmlPtr,
+  /// and ContentProtection elements.
-  // otherwise returns NULL ScopedXmlPtr.
+  /// @return On success returns a non-NULL ScopedXmlPtr. Otherwise returns a
+  ///         NULL ScopedXmlPtr.
   xml::ScopedXmlPtr<xmlNode>::type GetXml();
 
   // Must be unique in the Period.
@@ -117,35 +136,46 @@ class AdaptationSet {
   DISALLOW_COPY_AND_ASSIGN(AdaptationSet);
 };
 
-// In |media_info|, ContentProtectionXml::{schemeIdUri,value} takes precedence
+/// Representation class contains references to a single media stream, as
-// over schemeIdUri and value specified in ContentProtectionXml::attributes.
+/// well as optional ContentProtection elements for that stream.
 class Representation {
  public:
+  /// @param media_info is a MediaInfo containing information on the media.
+  /// @param representation_id is the numeric ID for the <Representation>.
   Representation(const MediaInfo& media_info, uint32 representation_id);
   ~Representation();
 
+  /// Tries to initialize the instance. If this does not succeed, the instance
+  /// should not be used.
+  /// @return true on success, false otherwise.
   bool Init();
 
-  // If |element| has {value, schemeIdUri} set and has
+  /// Add a ContenProtection element to the representation.
-  // {“value”, “schemeIdUri”} as key for additional_attributes,
+  /// @param element contains the ContentProtection element contents.
-  // then the former is used.
+  ///        If @a element has {value, schemeIdUri} set and has
+  ///        {“value”, “schemeIdUri”} as key for @a additional_attributes,
+  ///        then the former is used.
   void AddContentProtectionElement(const ContentProtectionElement& element);
 
+  /// Add a media segment to the representation.
+  /// @param start_time is the start time for the segment, in units of the
+  ///        stream's time scale.
+  /// @param duration is the duration of the segment, in units of the stream's
+  ///        time scale.
+  /// @return true on success, false otherwise.
   bool AddNewSegment(uint64 start_time, uint64 duration);
 
-  // Makes a copy of the current XML. Note that this is a copy. The caller is
+  /// @return Copy of <Representation>.
-  // responsible for cleaning up the allocated resource.
   xml::ScopedXmlPtr<xmlNode>::type GetXml();
 
-  // Must be unique amongst other Representations in the MPD file.
+  /// @return ID number for <Representation>.
-  // As the MPD spec says.
   uint32 id() const {
     return id_;
   }
 
  private:
-  // Returns whether |media_info_| has required fields to generate a valid
+  // Returns true if |media_info_| has required fields to generate a valid
-  // Representation. Returns true on success, otherwise returns false.
+  // Representation. Otherwise returns false.
   bool HasRequiredMediaInfoFields();
 
   // Note: Because 'mimeType' is a required field for a valid MPD, these return

mpd/base/mpd_notifier.h

@@ -18,34 +18,48 @@ namespace dash_packager {
 class ContentProtectionElement;
 class MediaInfo;
 
+/// Interface for publish/subscribe publisher class which notifies MpdBuilder
+/// of media-related events.
 class MpdNotifier {
  public:
   MpdNotifier() {};
   virtual ~MpdNotifier() {};
 
-  // Initializes the notifier. For example, if this notifier uses a network for
+  /// Initializes the notifier. For example, if this notifier uses a network for
-  // notification, then this would setup connection with the remote host.
+  /// notification, then this would set up the connection with the remote host.
+  /// @return true on success, false otherwise.
   virtual bool Init() = 0;
 
-  // Notifies the MpdBuilder that there is a new container along with
+  /// Notifies the MpdBuilder that there is a new container along with
-  // |media_info|. Live may have multiple "files" but those should be notified
+  /// @a media_info. Live may have multiple files (segments) but those should be
-  // via NotifyNewSegment().
+  /// notified via NotifyNewSegment().
-  // On success this populates |container_id| for the container and returns true,
+  /// @param media_info is the MediaInfo that will be passed to MpdBuilder.
-  // otherwise returns false.
+  /// @param[out] container_id is the numeric ID of the container, possibly for
+  ///             NotifyNewSegment() and AddContentProtectionElement(). Only
+  ///             populated on success.
+  /// @return true on success, false otherwise.
   virtual bool NotifyNewContainer(const MediaInfo& media_info,
                                   uint32* container_id) = 0;
 
-  // Only for Live. Notifies MpdBuilder that there is a new segment ready that
+  /// Notifies MpdBuilder that there is a new segment ready. Used only for live
-  // starts from |start_time| for |duration|.
+  /// profile.
-  // |container_id| must be an ID number populated by calling
+  /// @param container_id Container ID obtained from calling
-  // NotifyNewContainer().
+  ///        NotifyNewContainer().
+  /// @param start_time is the start time of the new segment, in units of the
+  ///        stream's time scale.
+  /// @param duration is the duration of the new segment, in units of the
+  ///        stream's time scale..
+  /// @return true on success, false otherwise.
   virtual bool NotifyNewSegment(uint32 container_id,
                                 uint64 start_time,
                                 uint64 duration) = 0;
 
-  // Adds content protection information to the MPD.
+  /// Adds content protection information to the MPD.
-  // |container_id| must be an ID number populated by calling
+  /// @param container_id is the nummeric container ID obtained from calling
-  // NotifyNewContainer().
+  ///        NotifyNewContainer().
+  /// @param content_protection_element New ContentProtection element
+  ///        specification.
+  /// @return true on success, false otherwise.
   virtual bool AddContentProtectionElement(
       uint32 container_id,
       const ContentProtectionElement& content_protection_element) = 0;

mpd/base/xml/scoped_xml_ptr.h

@@ -17,6 +17,8 @@
 namespace dash_packager {
 namespace xml {
 
+/// Deleter functor for deleting libxml2 pointers. This is used with
+/// ScopedXmlPtr.
 struct XmlDeleter {
   // Called by scoped_ptr. http://goo.gl/YaLbcS
   inline void operator()(xmlSchemaParserCtxtPtr ptr) const {
@@ -33,6 +35,7 @@ struct XmlDeleter {
 
 // C++11 allows template alias but standards before it do not. This struct is
 // for aliasing scoped_ptr with libxml2 object deleter.
+/// scoped_ptr for libxml2 resources.
 template <typename XmlType>
 struct ScopedXmlPtr {
   typedef scoped_ptr<XmlType, XmlDeleter> type;

mpd/base/xml/xml_node.h

@@ -21,40 +21,59 @@
 namespace dash_packager {
 namespace xml {
 
-// These classes are wrapper classes for XML elements for generating MPD.
+/// These classes are wrapper classes for XML elements for generating MPD.
-// None of the pointer parameters should be NULL. None of the methods are meant
+/// None of the pointer parameters should be NULL. None of the methods are meant
-// to be overridden.
+/// to be overridden.
 class XmlNode {
  public:
-  // Makes an XML element with |name|. |name| should not be NULL.
+  /// Make an XML element.
+  /// @param name is the name of the element, which should not be NULL.
   explicit XmlNode(const char* name);
   virtual ~XmlNode();
 
-  // The ownership transfers to this object. On failure, this method will
+  /// Add a child element to this element.
-  // destruct |child|.
+  /// @param child is a xmlNode to add as a child for this element. Ownership
+  ///        of the child node is transferred.
+  /// @return true on success, false otherwise.
   bool AddChild(ScopedXmlPtr<xmlNode>::type child);
 
+  /// Set a string attribute.
+  /// @param attribute_name The name (lhs) of the attribute.
+  /// @param attribute The value (rhs) of the attribute.
   void SetStringAttribute(const char* attribute_name,
                           const std::string& attribute);
 
+  /// Sets an interger attribute.
+  /// @param attribute_name The name (lhs) of the attribute.
+  /// @param number The value (rhs) of the attribute.
   void SetIntegerAttribute(const char* attribute_name, uint64 number);
+
+  /// Set a floating point number attribute.
+  /// @param attribute_name is the name of the attribute to set.
+  /// @param number is the value (rhs) of the attribute.
   void SetFloatingPointAttribute(const char* attribute_name, double number);
 
+  /// Sets 'id=@a id' attribute.
+  /// @param id is the ID for this element.
   void SetId(uint32 id);
 
-  // This is like 'innerHTML' setter.
+  /// Set the contents of an XML element using a string.
-  // This function does not work well with AddChild(). Use either AddChild() or
+  /// Note: This function does not work well with AddChild(). Use either
-  // SetContent() when setting the content of this node.
+  /// AddChild() or SetContent() when setting the content of this node.
+  /// @param content is a string containing the text-encoded child elements to
+  ///        be added to the element.
   void SetContent(const std::string& content);
 
-  // Ownership transfer. After calling this method, calling any methods of
+  /// Transfer the ownership of the xmlNodePtr. After calling this method, the
-  // this object, except the destructor, is undefined.
+  /// behavior of any methods, except the destructor, is undefined.
+  /// @return The resource of this object.
   ScopedXmlPtr<xmlNode>::type PassScopedPtr();
 
-  // Release the xmlNodePtr of this object. After calling this method, calling
+  /// Release the xmlNodePtr of this object. After calling this method, the
-  // any methods of this object, except the destructor, is undefined.
+  /// behavior of any methods, except the destructor, is undefined.
   xmlNodePtr Release();
 
+  /// @return Raw pointer to the element.
   xmlNodePtr GetRawPtr();
 
  private:
@@ -63,17 +82,19 @@ class XmlNode {
   DISALLOW_COPY_AND_ASSIGN(XmlNode);
 };
 
-// This corresponds to RepresentationBaseType in MPD. RepresentationBaseType is
+/// This corresponds to RepresentationBaseType in MPD. RepresentationBaseType is
-// not a concrete element type so this should not get instantiated on its own.
+/// not a concrete element type so this should not get instantiated on its own.
-// AdaptationSet and Representation are subtypes of this.
+/// AdaptationSet and Representation are subtypes of this.
 class RepresentationBaseXmlNode : public XmlNode {
  public:
   virtual ~RepresentationBaseXmlNode();
   bool AddContentProtectionElements(
       const std::list<ContentProtectionElement>& content_protection_elements);
 
-  // Return true on success. If content_protections size is 0 in |media_info|,
+  /// Add a ContentProtection elements to this element.
-  // this will return true. Otherwise return false.
+  /// @param media_info is a MediaInfo containing the ContentProtection
+  ///        elements to add.
+  /// @return true on success, false otherwise.
   bool AddContentProtectionElementsFromMediaInfo(const MediaInfo& media_info);
 
  protected:
@@ -86,7 +107,7 @@ class RepresentationBaseXmlNode : public XmlNode {
   DISALLOW_COPY_AND_ASSIGN(RepresentationBaseXmlNode);
 };
 
-// AdaptationSetType in MPD.
+/// AdaptationSetType specified in MPD.
 class AdaptationSetXmlNode : public RepresentationBaseXmlNode {
  public:
   AdaptationSetXmlNode();
@@ -96,7 +117,7 @@ class AdaptationSetXmlNode : public RepresentationBaseXmlNode {
   DISALLOW_COPY_AND_ASSIGN(AdaptationSetXmlNode);
 };
 
-// RepresentationType in MPD.
+/// RepresentationType in MPD.
 class RepresentationXmlNode : public RepresentationBaseXmlNode {
  public:
   typedef ::google::protobuf::RepeatedPtrField<MediaInfo_VideoInfo>
@@ -108,17 +129,29 @@ class RepresentationXmlNode : public RepresentationBaseXmlNode {
   RepresentationXmlNode();
   virtual ~RepresentationXmlNode();
 
-  // Returns true if successfully set attributes and children elements (if
+  /// Adds video metadata to the MPD.
-  // applicable). repeated info of size 0 is valid input.
+  /// @param repeated_video_info constains the VideoInfos for Representation.
+  ///        Input of size 0 is valid.
+  /// @return true if successfully set attributes and children elements (if
+  ///         applicable), false otherwise.
   bool AddVideoInfo(const RepeatedVideoInfo& repeated_video_info);
+
+  /// Adds audio metadata to the MPD.
+  /// @param repeated_audio_info constains the AudioInfos for Representation.
+  ///        Input of size 0 is valid.
+  /// @return true if successfully set attributes and children elements (if
+  ///         applicable), false otherwise.
   bool AddAudioInfo(const RepeatedAudioInfo& repeated_audio_info);
 
-  // Check MediaInfo protobuf definition for which fields are specific to VOD.
+  /// Adds fields that are specific to VOD. This ignores @a media_info fields for
+  /// Live.
+  /// @param media_info is a MediaInfo with VOD information.
+  /// @return true on success, false otherwise.
   bool AddVODOnlyInfo(const MediaInfo& media_info);
 
  private:
   // Add AudioChannelConfiguration elements. This will add multiple
-  // AudioChannelConfiguration if |repeated_audio_info| contains multiple
+  // AudioChannelConfiguration if @a repeated_audio_info contains multiple
   // distinct channel configs (e.g. 2 channels and 6 channels adds 2 elements).
   bool AddAudioChannelInfo(const RepeatedAudioInfo& repeated_audio_info);