[xiph-commits] r8700 - trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags

illiminable at motherfish-iii.xiph.org illiminable at motherfish-iii.xiph.org
Sat Jan 8 22:30:23 PST 2005


Author: illiminable
Date: 2005-01-08 22:30:22 -0800 (Sat, 08 Jan 2005)
New Revision: 8700

Modified:
   trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_BaseTag.h
   trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_CMMLDoc.h
   trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_CMMLPreamble.h
   trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_CMMLRootTag.h
   trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_CMMLTag.h
   trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_ClipTag.h
   trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_ClipTagList.h
   trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_DescTag.h
   trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_HeadTag.h
   trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_HumReadCMMLTag.h
   trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_ImageTag.h
   trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_ImportTag.h
   trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_ImportTagList.h
   trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_MappedTag.h
   trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_MappedTagList.h
   trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_MetaTag.h
   trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_MetaTagList.h
   trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_ParamTag.h
   trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_ParamTagList.h
   trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_StreamTag.h
   trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_TagList.h
   trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_TextFieldTag.h
   trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_TitleTag.h
Log:
* Documented libCMMLTags

Modified: trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_BaseTag.h
===================================================================
--- trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_BaseTag.h	2005-01-09 06:08:24 UTC (rev 8699)
+++ trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_BaseTag.h	2005-01-09 06:30:22 UTC (rev 8700)
@@ -49,22 +49,26 @@
 	C_BaseTag(void);
 	virtual ~C_BaseTag(void);
 
-	//Accessors
+	/// Returns the base uri that is used for this cmml document.
 	wstring href();
 
-	//Mutators
+	/// Sets the base uri used for this cmml document.
 	void setHref(wstring inHref);
 
-	//Other
+	/// Converts this tag to an xml string.
 	virtual wstring toString();
+
+	/// Performs a deep copy returning a pointer you can keep.
 	C_BaseTag* clone();
+
+	/// Performs a deep copy returning a pointer to the base class you can keep.
 	virtual C_CMMLTag* genericClone();
 
 protected:
 	//Property Data
 	wstring mHref;
 
-	//Protected Helper Methods
+	/// Internal cloning mechanism
 	virtual void privateClone(C_CMMLTag* outTag);
 
 };

Modified: trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_CMMLDoc.h
===================================================================
--- trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_CMMLDoc.h	2005-01-09 06:08:24 UTC (rev 8699)
+++ trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_CMMLDoc.h	2005-01-09 06:30:22 UTC (rev 8700)
@@ -33,12 +33,6 @@
 */
 
 #pragma once
-//These are the original callbacks... need to provide an interface that does not 
-//include the C structs and hopefully no void*
-//
-//typedef int (*CMMLReadStreamCB)  (CMML *cmml, const CMML_Stream *stream, void * user_data);
-//typedef int (*CMMLReadHeadCB)   (CMML *cmml, const CMML_Head *head, void * user_data);
-//typedef int (*CMMLReadClipCB) (CMML *cmml, const CMML_Clip *clip, void * user_data);
 
 //STL Include Files
 #include <string>
@@ -47,14 +41,8 @@
 //Local Include Files
 #include <libCMMLTags/C_CMMLPreamble.h>
 #include <libCMMLTags/C_CMMLRootTag.h>
-//#include <libCMMLTags/C_CMMLError.h>
 
 
-//typedef int (*CMMLReadStreamCB)  (const C_StreamTag *inStream, void * user_data);
-//typedef int (*CMMLReadHeadCB)   (const C_HeadTag *inHead, void * user_data);
-//typedef int (*CMMLReadClipCB) (const C_ClipTag *inClip, void * user_data);
-
-
 class LIBCMMLTAGS_API C_CMMLDoc
 {
 public:
@@ -62,103 +50,22 @@
 	C_CMMLDoc(void);
 	virtual ~C_CMMLDoc(void);
 
+	/// Returns an internal pointer to the preamble element. Can manipulate but not delete.
 	C_CMMLPreamble* preamble();
+
+	/// Returns and internal pointer to the cmml root tag. Can manipulate but not delete.
 	C_CMMLRootTag* root();
 
+	/// Sets the root cmml tag for this document.
 	void setRoot(C_CMMLRootTag* inRootTag);
 
+	/// Returns an xml string representing the complete document.
 	virtual wstring toString();
-	C_CMMLDoc* clone();
-	
 
-	//Opening files
-	//bool open(wstring inFilename);
-	//bool open(wstring inFilename, CMMLReadStreamCB inStreamCB, CMMLReadHeadCB inHeadCB, CMMLReadClipCB inClipCB);
-	//ISSUE ::: Void pointer on interface...
-	//bool open(wstring inFilename, CMMLReadStreamCB inStreamCB, CMMLReadHeadCB inHeadCB, CMMLReadClipCB inClipCB, void* inUserData);
-	//ISSUE ::: Find a way to allow the passing in of a fstream
-	
-	
 
-	//Close the file. Releases resources but leaves the object capable of handling
-	//another file.
-	//void close();
+	C_CMMLDoc* clone();
 
-	//Load all the callbacks if they were unknown at open
-	// or if they have to be changed mid parse.
-	//bool setCallbacks(CMMLReadStreamCB inStreamCB, CMMLReadHeadCB inHeadCB, CMMLReadClipCB inClipCB, void* inUserData);
-
-	//Ask the underlying library to read a certain number of bytes
-	//void read(unsigned long inNumBytes);
-
-	//The the underlying library to read to the end of the file.
-	// This is useful to do initially to read the entire file
-	//void readToEnd();
-
-	//Resets the filestream, removes all stored tag data, but DOES NOT
-	// remove the file stream or the callbacks
-	//void resetFile();
-
-	//Removes the associated file, removes all stored tag data, resets all the
-	// callbacks. This brings it back to it's initial state as it was when
-	// constructed with no parameters before it was attached to any files or callbacks.
-
-	//Currently just clear all tags by deleting them
-	//void clearAll();
-
-	//Accessors
-	//Is the file ready to go. ie has a file been attached and opened.
-	//bool isStreamReady();
-
-	//NO READ OPERATIONS CAN TAKE PLACE WHILE EITHER OF THE TWO FOLLOWING REPORT TRUE
-
-	//Is it at the end of the file
-	//bool isEOF();
-
-	//Is there an error reading the stream.
-	//bool isStreamError();
-
-	//Returns a pointer to the last CMML error. Or NULL if no error.
-	//These are parsing errors. They ARE NOT the same as the stream errors.
-	//They represent badly formatted documents not errors in reading the data.
-	//You shouldn't call this unless CMMLError is true.
-	//C_CMMLError* lastCMMLError();
-
-	//Returns if there is a CMML error pending.
-	//bool isCMMLError();
-
-	//ALL THE FOLLOWING WILL RETURN NULL IF THEY DON"T EXIST OR HAVE NOT BEEN 
-	// READ YET.
-	
-	//Returns a pointer to the list of clips already read. Should never return NULL
-	// As each new clip is read it is appended to the end of the clip list.
-	// The clip list object can tell you about how many clips have been read
-	// and you can access them by number.
-	//ISSUE ::: Should they also be able to be retrieved by id ??
-	//C_ClipTagList* clipList();
-
-	//Returns a pointer to the most recently read clip or if the entire file is
-	// read the last clip in the file
-	//C_ClipTag* lastClip();
-
-	//Returns a pointer to the second last clip that waas read or if the entire file
-	// has been read, the previous clip in the file.
-	//C_ClipTag* previousClip();
-
-
-
-
 protected:
 	C_CMMLPreamble* mPreamble;
 	C_CMMLRootTag* mRoot;
-
-
-	//bool mIsStreamReady;
-	//bool mIsEOF;
-	//bool mIsStreamError;
-
-
-
-	//C_CMMLError* mLastError;
-	
 };

Modified: trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_CMMLPreamble.h
===================================================================
--- trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_CMMLPreamble.h	2005-01-09 06:08:24 UTC (rev 8699)
+++ trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_CMMLPreamble.h	2005-01-09 06:30:22 UTC (rev 8700)
@@ -44,37 +44,31 @@
 	C_CMMLPreamble(void);
 	virtual ~C_CMMLPreamble(void);
 
-
-
-	//Accessors
+	/// Returns the xml version in the preamble.
 	wstring xmlVersion();
+
+	/// Returns the encoding in the preamble.
 	wstring xmlEncoding();
+
+	/// Returns whether this document stands alone.
 	wstring xmlStandAlone();
 	
-	//Mutators
+	/// Sets the xml version for this document.
 	void setXmlVersion(wstring inVersion);
+
+	/// Sets the encoding for this document.
 	void setXmlEncoding(wstring inEncoding);
+
+	/// Sets the standalone property.
 	void setXmlStandAlone(wstring inStandAlone);
 
-	//Others
+	/// Returns an xml string of the preamble.
 	virtual wstring toString();
+
+	/// Performs a deep copy of the preamble returning a pointer you can keep.
 	C_CMMLPreamble* clone();
 
-
 protected:
-	//Original Structure
-	//
-	//typedef struct {
-	//	char *xml_version;      /**< version attribute of xml proc instr */
-	//	char *xml_encoding;     /**< encoding attribute of xml proc instr */
-	//	int   xml_standalone;   /**< standalone attribute of xml proc instr */
-	//	int   doctype_declared; /**< was doctype declared */
-	//	char *cmml_lang;        /**< lang attribute of cmml tag */
-	//	char *cmml_dir;         /**< dir attribute of cmml tag */
-	//	char *cmml_id;          /**< id attribute of cmml tag */
-	//	char *cmml_xmlns;       /**< xmlns attribute of cmml tag */
-	//} CMML_Preamble;
-
 	//Property Data
 	wstring mXmlVersion;
 	wstring mXmlEncoding;

Modified: trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_CMMLRootTag.h
===================================================================
--- trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_CMMLRootTag.h	2005-01-09 06:08:24 UTC (rev 8699)
+++ trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_CMMLRootTag.h	2005-01-09 06:30:22 UTC (rev 8700)
@@ -53,30 +53,39 @@
 	C_CMMLRootTag(void);
 	virtual ~C_CMMLRootTag(void);
 
-	//Accessors
-	
+	/// Returns the internal pointer to the stream element. Can modify but don't delete.	
 	C_StreamTag* stream();
+
+	/// Returns the internal pointer to the head element. Can modify but don't delete.
 	C_HeadTag* head();
+
+	/// Returns the internal pointer to the clip list. Can modify but don't delete.
 	C_ClipTagList* clipList();
 
-	//Mutators
+	/// Sets the stream element. You give away your pointer.
 	void setStream(C_StreamTag* inStreamTag);
+
+	/// Sets the head element. You give away your pointer.
 	void setHead(C_HeadTag* inHeadTag);
+
+	/// Sets the clip list. You give away your pointer.
 	void setClipList(C_ClipTagList* inClipList);
 
-	//Other
+	/// Returns an xml string representing the root tag.
 	virtual wstring toString();
-	virtual C_CMMLTag* genericClone();
+
+	/// Does a deep copy of this tag and returns a pointer you can keep.
 	C_CMMLRootTag* clone();
 
+	/// Does a deep copy of this tag and returns a pointer to the base class you can keep.
+	virtual C_CMMLTag* genericClone();
+
 protected:
 	//Property Data
-	
 	C_StreamTag* mStream;
 	C_HeadTag* mHead;
 	C_ClipTagList* mClipList;
 
-	//Protected Helper Methods
+	/// Internal deep copy mechanism.
 	virtual void privateClone(C_CMMLTag* outTag);
-
 };

Modified: trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_CMMLTag.h
===================================================================
--- trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_CMMLTag.h	2005-01-09 06:08:24 UTC (rev 8699)
+++ trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_CMMLTag.h	2005-01-09 06:30:22 UTC (rev 8700)
@@ -70,15 +70,16 @@
 		BAD_TAG = 1000
 	};
 	
-	//Accessors
+	/// Returns the id attribute for this tag.
 	wstring id();
 
-	//Mutators
+	/// Sets the id attribute for this tag.
 	void setId(wstring inId);
 
+	/// Returns the type of tag this really is.
 	eTagType tagType();
 
-	//Other
+	/// Pure Virtual : Returns an xml string representing this tag.
 	virtual wstring toString() = 0;
 protected:
 	//Property Data
@@ -87,7 +88,11 @@
 
 	//Protected Helper Methods
 	virtual void privateClone(C_CMMLTag* outTag);
+
+	/// Makes an attribute of the form name="content" and returns a string.
 	wstring makeElement(wstring inElemName, wstring inElemContent);
-	wstring C_CMMLTag::makeRequiredElement(wstring inElemName, wstring inElemContent);
+
+
+	wstring makeRequiredElement(wstring inElemName, wstring inElemContent);
 	
 };

Modified: trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_ClipTag.h
===================================================================
--- trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_ClipTag.h	2005-01-09 06:08:24 UTC (rev 8699)
+++ trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_ClipTag.h	2005-01-09 06:30:22 UTC (rev 8700)
@@ -54,35 +54,61 @@
 	//Constructors
 	C_ClipTag(void);
 	virtual ~C_ClipTag(void);
-	
 
-	//Accessors
+	/// Returns the name of the track this clip belongs to.
 	wstring track();
+
+	/// Returns a pointer to the internal metatag list. Don't delete.
 	C_MetaTagList* metaList();
+
+	/// Returns a pointer to the internal anchor element. Don't delete.
 	C_AnchorTag* anchor();
+
+	/// Returns a pointer to the internal image element. Don't delete.
 	C_ImageTag* image();
+
+	/// Returns a pointer to the internal desc element. Don't delete.
 	C_DescTag* desc();
 
+	/// Returns the start time for this clip.
 	wstring start();
+
+	/// Returns the end time for this clip. May be "".
 	wstring end();
 
 
-	//Mutators
+	/// Set the track this clip belongs to.
 	void setTrack(wstring inTrack);
+
+	/// Set the anchor tag for this clip. You give away your pointer.
 	void setAnchor(C_AnchorTag* inAnchor);
+
+	/// Set the image tag for this clip. You give away your pointer.
 	void setImage(C_ImageTag* inImage);
+
+	/// Sets the desc tag for this clip. You give away your pointer.
 	void setDesc(C_DescTag* inDesc);
 
+	/// Sets the start time for this clip.
 	void setStart(wstring inStart);
+
+	/// Sets the end time for this clip. May be "".
 	void setEnd(wstring inEnd);
 
+	/// Converts this tag to an xml string.
+	virtual wstring toString();
 
-	//Others
-	virtual wstring toString();
+	/// Performs a deep copy returning a pointer you can keep.
 	C_ClipTag* clone();
+
+	/// Performs a deep copy returning a pointer to the base class you can keep.
 	virtual C_CMMLTag* genericClone();
 
 protected:
+	/// Internal deep copy mechanism
+	virtual void privateClone(C_CMMLTag* outTag);
+
+
 	//Property Data
 	wstring mTrack;
 	C_MetaTagList* mMetaList;
@@ -92,10 +118,4 @@
 
 	wstring mStart;
 	wstring mEnd;
-
-	//Protected Helper Methods
-	virtual void privateClone(C_CMMLTag* outTag);
-
-
-
 };

Modified: trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_ClipTagList.h
===================================================================
--- trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_ClipTagList.h	2005-01-09 06:08:24 UTC (rev 8699)
+++ trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_ClipTagList.h	2005-01-09 06:30:22 UTC (rev 8700)
@@ -41,7 +41,6 @@
 #include <libCMMLTags/C_TagList.h>
 #include <libCMMLTags/C_ClipTag.h>
 
-//TO DO:::Make this class !
 class LIBCMMLTAGS_API C_ClipTagList :
 	//Derived Classes
 	public C_TagList
@@ -51,12 +50,18 @@
 	C_ClipTagList(void);
 	virtual ~C_ClipTagList(void);
 
+	/// Adds a tag to the list. You give away your pointer.
+	void addTag(C_ClipTag* inTag);
 
+	/// Gets a pointer to a tag in the list you can manipulate but not delete.
+	C_ClipTag* getTag(unsigned long inTagNo);
+
+	/// Converts the list of clips into an xml string.
 	virtual wstring toString();
+
+	/// Does a deep copy and returns a pointer you can keep.
 	C_ClipTagList* clone();
 
-	void addTag(C_ClipTag* inTag);
-	C_ClipTag* getTag(unsigned long inTagNo);
 
 	virtual void privateClone(C_TagList* outTagList);
 };

Modified: trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_DescTag.h
===================================================================
--- trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_DescTag.h	2005-01-09 06:08:24 UTC (rev 8699)
+++ trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_DescTag.h	2005-01-09 06:30:22 UTC (rev 8700)
@@ -49,14 +49,17 @@
 	C_DescTag(void);
 	virtual ~C_DescTag(void);
 
-	//Other
+	/// Returns an xml strnig representing this tag.
 	virtual wstring toString();
+
+	/// Performs a deep copy and returns a pointer you can keep.
 	C_DescTag* clone();
+
+	/// Performs a deep copy and returns a pointer to the base class you can keep.
 	virtual C_CMMLTag* genericClone();
 
 protected:
-	//Protected Helper Methods
+
+	/// Internal deep copy mechanism.
 	virtual void privateClone(C_CMMLTag* outTag);
-
-	
 };

Modified: trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_HeadTag.h
===================================================================
--- trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_HeadTag.h	2005-01-09 06:08:24 UTC (rev 8699)
+++ trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_HeadTag.h	2005-01-09 06:30:22 UTC (rev 8700)
@@ -52,20 +52,34 @@
 	C_HeadTag(void);
 	virtual ~C_HeadTag(void);
 
-	//Accessors
+	/// Returns uri for profile used in meta tags (eg Dublin Core)
 	wstring profile();
+
+	/// Returns an internal pointer to the title element. Can modify but don't delete.
 	C_TitleTag* title();
+
+	/// Returns an internal pointer to the base element. Can modify but don't delete.
 	C_BaseTag* base();
+
+	/// Returns an internal pointer to the meta tag list. Can modify but don't delete.
 	C_MetaTagList* metaList();
 
-	//Mutators
+	/// Sets the uri for the profile used in meta tags.
 	void setProfile(wstring inProfile);
+
+	/// Sets the title tag for this element. You give away your pointer.
 	void setTitle(C_TitleTag* inTitle);
+
+	/// Sets the base tag for this element. You give away your pointer.
 	void setBase(C_BaseTag* inBase);
 
-	//Other
+	/// Returns an xml representation of this tag.
 	virtual wstring toString();
+
+	/// Performs a deep copy and returns a pointer you can keep.
 	C_HeadTag* clone();
+
+	/// Performs a deep copy and returns a pointer to the base class you can keep.
 	virtual C_CMMLTag* genericClone();
 protected:
 	//Property Data

Modified: trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_HumReadCMMLTag.h
===================================================================
--- trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_HumReadCMMLTag.h	2005-01-09 06:08:24 UTC (rev 8699)
+++ trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_HumReadCMMLTag.h	2005-01-09 06:30:22 UTC (rev 8700)
@@ -48,15 +48,19 @@
 	C_HumReadCMMLTag(void);
 	virtual ~C_HumReadCMMLTag(void);
 
-	//Accessors
+	/// Returns the language country code for this tag (eg. en or de)
 	wstring lang();
+
+	/// Returns the direction this langauge is read (ltr or rtl)
 	wstring dirn();
 
-	//Mutators
+	/// Sets the language country code for this tag (eg. en or de)
 	void setLang(wstring inLang);
+
+	/// Sets the direction this langauge is read (ltr or rtl)
 	void setDirn(wstring inDirn);
 
-	//Other
+	/// Returns an xml representation of this tag.
 	virtual wstring toString() = 0;
 
 protected:

Modified: trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_ImageTag.h
===================================================================
--- trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_ImageTag.h	2005-01-09 06:08:24 UTC (rev 8699)
+++ trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_ImageTag.h	2005-01-09 06:30:22 UTC (rev 8700)
@@ -49,17 +49,25 @@
 	C_ImageTag(void);
 	virtual ~C_ImageTag(void);
 
-	//Accessors
+	/// Returns the uri which is the source for this image.
 	wstring src();
+
+	/// Returns the alternate text for this image.
 	wstring alt();
 
-	//Mutators
+	/// Sets the uri which is the source for this image.
 	void setSrc(wstring inSrc);
+
+	/// Setss the alternate text for this image.
 	void setAlt(wstring inAlt);
 
-	//Other
+	/// Returns an xml representation of this tag.
 	virtual wstring toString();
+
+	/// Performs a deep copy and returns a pointer you can keep.
 	C_ImageTag* clone();
+
+	/// Performs a deep copy and returns a pointer to the base class you can keep.
 	virtual C_CMMLTag* genericClone();
 protected:
 	//Property Data

Modified: trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_ImportTag.h
===================================================================
--- trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_ImportTag.h	2005-01-09 06:08:24 UTC (rev 8699)
+++ trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_ImportTag.h	2005-01-09 06:30:22 UTC (rev 8700)
@@ -51,27 +51,55 @@
 	C_ImportTag(void);
 	virtual ~C_ImportTag(void);
 
-	//Accessors
+	/// Returns the granule rate for this imported media
 	wstring granuleRate();
+
+	/// Returns the content type (MIME type) of this imported media.
 	wstring contentType();
+
+	/// Returns the uri of the imported media.
 	wstring src();
+
+	/// Returns the start time for this imported media
 	wstring start();
+
+	/// Returns the end time for this imported media.
 	wstring end();
+
+	/// Returns the title of this imported media.
 	wstring title();
+
+	/// Returns an internal poitner to the param list. Can modify but don't delete.
 	C_ParamTagList* paramList();
 
-	//Mutators
+	/// Sets the granule rate for this imported media
 	void setGranuleRate(wstring inGranuleRate);
+
+	/// Sets the content type (MIME type) of this imported media.
 	void setContentType(wstring inContentType);
+
+	/// Sets the uri of the imported media.
 	void setSrc(wstring inSrc);
+
+	/// Sets the start time for this imported media
 	void setStart(wstring inStart);
+
+	/// Sets the end time for this imported media.
 	void setEnd(wstring inEnd);
+
+	/// Sets the title of this imported media.
 	void setTitle(wstring inTitle);
+
+	/// Sets the internal poitner to the param list. You give away your pointer.
 	void setParamList(C_ParamTagList* inParamList);
 
-	//Other
+	/// Returns an xml representation of this tag.
 	virtual wstring toString();
+
+	/// Performs a deep copy and returns a pointer you can keep.
 	C_ImportTag* clone();
+
+	/// Performs a deep copy and returns a pointer to the base class you can keep.
 	virtual C_CMMLTag* genericClone();
 
 protected:

Modified: trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_ImportTagList.h
===================================================================
--- trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_ImportTagList.h	2005-01-09 06:08:24 UTC (rev 8699)
+++ trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_ImportTagList.h	2005-01-09 06:30:22 UTC (rev 8700)
@@ -49,10 +49,16 @@
 	C_ImportTagList(void);
 	virtual ~C_ImportTagList(void);
 
+	/// Returns an xml representation of this tag.
 	virtual wstring toString();
+
+	/// Performs a deep copy and returns a pointer to the base class you can keep.
 	C_ImportTagList* clone();
 
+	/// Adds a tag to the list. You give away your poitner.
 	void addTag(C_ImportTag* inTag);
+
+	/// Gets a tag from the list. You can modify but don't delete.
 	C_ImportTag* getTag(unsigned long inTagNo);
 
 protected:

Modified: trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_MappedTag.h
===================================================================
--- trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_MappedTag.h	2005-01-09 06:08:24 UTC (rev 8699)
+++ trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_MappedTag.h	2005-01-09 06:30:22 UTC (rev 8700)
@@ -50,16 +50,22 @@
 	C_MappedTag(wstring inName, wstring inContent);
 	virtual ~C_MappedTag(void);
 
-	//Accessors
+	/// Returns the name (key) for this mapped pair.
 	wstring name();
+
+	/// Returns the content of this mapped pair.
 	wstring content();
 
-	//Mutators
+	/// Sets the name (key) for this mapped pair.
 	void setName(wstring inName);
+
+	/// Sets the content of this mapped pair.
 	void setContent(wstring inContent);
 
-	//Other
+	/// Pure Virtual :  Returns an xml representation of this tag.
 	virtual wstring toString() = 0;
+
+	/// Pure Virtual : Performs a deep copy of this tag.
 	virtual C_MappedTag* mappedClone() = 0;
 
 protected:

Modified: trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_MappedTagList.h
===================================================================
--- trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_MappedTagList.h	2005-01-09 06:08:24 UTC (rev 8699)
+++ trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_MappedTagList.h	2005-01-09 06:30:22 UTC (rev 8700)
@@ -47,21 +47,15 @@
 	C_MappedTagList(void);
 	virtual ~C_MappedTagList(void);
 
-	//What to do about this ? **** They are now protected dervied classes implement themselves
-	//void addTag(wstring inName, wstring inContent);
-	
-	//void removeTag ???
+	/// Returns the tags in this list.
 	unsigned long numTags();
 
+	/// Gets the content of a mapped element by name.
 	wstring getContent(wstring mName);
 
-	//Maybe not !
-	//void addTag(wstring inName, wstring inContent);
-
+	/// Returns an xml representation of this tag.
 	virtual wstring toString() = 0;
 	
-
-
 protected:
 	vector<C_MappedTag*> mTagList;
 

Modified: trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_MetaTag.h
===================================================================
--- trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_MetaTag.h	2005-01-09 06:08:24 UTC (rev 8699)
+++ trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_MetaTag.h	2005-01-09 06:30:22 UTC (rev 8700)
@@ -49,16 +49,22 @@
 	C_MetaTag(void);
 	virtual ~C_MetaTag(void);
 
-	//Accessors
+	/// The uri for the scheme used in this mapping (ie dublin core)
 	wstring scheme();
 
-	//Mutators
+	/// Sets the uri for the scheme used in this meta tag.
 	void setScheme(wstring inScheme);
 
-	//Other
+	/// Returns an xml representation of this tag.
 	virtual wstring toString();
+
+	/// Performs a deep copy and returns a pointer you can keep.
 	C_MetaTag* clone();
+
+	/// Performs a deep copy and returns a pointer to the base class you can keep.
 	virtual C_CMMLTag* genericClone();
+
+	/// Performs a deep copy and returns a pointer to the mapped base class you can keep.
 	virtual C_MappedTag* mappedClone();
 
 protected:

Modified: trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_MetaTagList.h
===================================================================
--- trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_MetaTagList.h	2005-01-09 06:08:24 UTC (rev 8699)
+++ trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_MetaTagList.h	2005-01-09 06:30:22 UTC (rev 8700)
@@ -42,18 +42,28 @@
 	C_MetaTagList(void);
 	virtual ~C_MetaTagList(void);
 
+	/// Empties the list.
 	void emptyList();
+
+	/// Adds a tag to the list. You give away your pointer.
 	void addTag(C_MetaTag* inTag);
+
+	/// Adds a tag to this list by specifying name and content.
 	void addTag(wstring inName, wstring inContent);
-	//void removeTag ???
-	//unsigned long numTags();
 
+	/// Gets the indexed tag from the list. You can modify but not delete the pointer.
 	C_MetaTag* getTag(unsigned long inTagNo);
+
+	/// Returns a pointer to the tag with this name. You can modify but not delete.
 	C_MetaTag* getTag(wstring inName);
 
+	/// Gets the matching content from the tag with given name.
 	wstring getContent(wstring inName);
+	
+	/// Returns an xml representation of this tag.
+	virtual wstring toString();
 
-	virtual wstring toString();
+	/// Performs a deep copy and returns a pointer you can keep.
 	C_MetaTagList* clone();
 protected:
 	//Protected Helper Methods

Modified: trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_ParamTag.h
===================================================================
--- trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_ParamTag.h	2005-01-09 06:08:24 UTC (rev 8699)
+++ trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_ParamTag.h	2005-01-09 06:30:22 UTC (rev 8700)
@@ -49,10 +49,16 @@
 	C_ParamTag(void);
 	virtual ~C_ParamTag(void);
 
-	//Other
+	/// Returns an xml representation of this tag.
 	virtual wstring toString();
+
+	/// Performs a deep copy and returns a pointer you can keep.
 	C_ParamTag* clone();
+
+	/// Performs a deep copy and returns a pointer to the base class you can keep.
 	virtual C_CMMLTag* genericClone();
+
+	/// Performs a deep copy and returns a pointer to the base mapped class you can keep.
 	virtual C_MappedTag* mappedClone();
 
 protected:

Modified: trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_ParamTagList.h
===================================================================
--- trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_ParamTagList.h	2005-01-09 06:08:24 UTC (rev 8699)
+++ trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_ParamTagList.h	2005-01-09 06:30:22 UTC (rev 8700)
@@ -51,15 +51,15 @@
 	C_ParamTagList(void);
 	virtual ~C_ParamTagList(void);
 
-	//Accessors
+	/// Gets the indexed tag.
 	C_ParamTag* getTag(unsigned long inTagNo);
 
-	//Mutators
+	/// Adds a tag to the list. You give away your poitner.
 	void addTag(C_ParamTag* inTag);
 	
+	/// Returns an xml representation of this tag.
+	virtual wstring toString();
 
-	//Other
-	virtual wstring toString();
+	/// Performs a deep copy and returns a pointer you can keep.
 	C_ParamTagList* clone();
-	
 };

Modified: trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_StreamTag.h
===================================================================
--- trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_StreamTag.h	2005-01-09 06:08:24 UTC (rev 8699)
+++ trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_StreamTag.h	2005-01-09 06:30:22 UTC (rev 8700)
@@ -50,23 +50,33 @@
 	C_StreamTag(void);
 	virtual ~C_StreamTag(void);
 
-	//Accessors
+	/// Returns the timebase of this stream
 	wstring timebase();
+
+	/// Returns a utc timebase (if any) of this stream
 	wstring utc();
+
+	/// Returns an internal pointer to the import list. Can modify but not delete.
 	C_ImportTagList* importList();
 
-	//Mutators
+	/// Sets the timebase of this stream
 	void setTimebase(wstring inTimebase);
+
+	/// Sets a utc timebase (if any) of this stream
 	void setUtc(wstring inUtc);
+
+	/// Sets the internal pointer to the import list. You give away your pointer.
 	void setImportList(C_ImportTagList* inTagList);
 
-	//Other
+	/// Returns an xml representation of this tag.
 	virtual wstring toString();
+	
+	/// Performs a deep copy and returns a pointer you can keep.
 	C_StreamTag* clone();
+
+	/// Performs a deep copy and returns a pointer to the base class you can keep.	
 	virtual C_CMMLTag* genericClone();
 
-
-
 protected:
 	//Property Data
 	wstring mTimebase;

Modified: trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_TagList.h
===================================================================
--- trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_TagList.h	2005-01-09 06:08:24 UTC (rev 8699)
+++ trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_TagList.h	2005-01-09 06:30:22 UTC (rev 8700)
@@ -49,12 +49,10 @@
 	C_TagList(void);
 	virtual ~C_TagList(void);
 	
-	//void removeTag ???
-
-	//Accessors
+	/// Returns the number of tags in this list
 	unsigned long numTags();
 
-	//Other
+	/// Returns an xml representation of this tag.
 	virtual wstring toString() = 0;
 
 protected:

Modified: trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_TextFieldTag.h
===================================================================
--- trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_TextFieldTag.h	2005-01-09 06:08:24 UTC (rev 8699)
+++ trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_TextFieldTag.h	2005-01-09 06:30:22 UTC (rev 8700)
@@ -49,13 +49,13 @@
 	C_TextFieldTag(void);
 	virtual ~C_TextFieldTag(void);
 
-	//Accessors
+	/// Returns the inner text associated with this tag.
 	wstring text();
 	
-	//Mutators
+	/// Sets the inner text associated with this tag/	
 	void setText(wstring inText);
 
-	//Other
+	/// Returns an xml representation of this tag.
 	virtual wstring toString() = 0;
 protected:
 	//Property Data

Modified: trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_TitleTag.h
===================================================================
--- trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_TitleTag.h	2005-01-09 06:08:24 UTC (rev 8699)
+++ trunk/oggdsf/src/lib/codecs/cmml/libCMMLTags/C_TitleTag.h	2005-01-09 06:30:22 UTC (rev 8700)
@@ -49,9 +49,13 @@
 	C_TitleTag(void);
 	virtual ~C_TitleTag(void);
 
-	//Other
+	/// Returns an xml representation of this tag.
 	virtual wstring toString();
+
+	/// Performs a deep copy and returns a pointer you can keep.
 	C_TitleTag* clone();
+
+	/// Performs a deep copy and returns a pointer to the base class you can keep.
 	virtual C_CMMLTag* genericClone();
 protected:
 	//Protected Helper Methods



More information about the commits mailing list