[Gnash-commit] /srv/bzr/gnash/rtmp r9694: cleanup up doxygen comnments.

[rob]

------------------------------------------------------------
revno: 9694
committer: address@hidden
branch nick: rtmp
timestamp: Mon 2008-11-03 12:33:59 -0700
message:
  cleanup up doxygen comnments.
modified:
  cygnal/crc.h
  cygnal/diskstream.cpp
  cygnal/diskstream.h

=== modified file 'cygnal/crc.h'
--- a/cygnal/crc.h      2008-11-03 19:25:44 +0000
+++ b/cygnal/crc.h      2008-11-03 19:33:59 +0000
@@ -93,7 +93,7 @@
     /// \brief Set the  flag for whether to enable the administration thread.
     void setAdminFlag(bool x) { _admin = x; }
 
-    ///  \brief Dump the internal data of this class in a human readable form.
+    /// \brief Dump the internal data of this class in a human readable form.
     /// @remarks This should only be used for debugging purposes.
     void dump() const { dump(std::cerr); }
     

=== modified file 'cygnal/diskstream.cpp'
--- a/cygnal/diskstream.cpp     2008-11-03 19:13:15 +0000
+++ b/cygnal/diskstream.cpp     2008-11-03 19:33:59 +0000
@@ -46,6 +46,8 @@
 // gnash::LogFile& dbglogfile = gnash::LogFile::getDefaultInstance();
 // }
 
+/// \namespace cygnal
+///    This namespace is for all the Cygnal specific classes.
 namespace cygnal {
 
 /// \def _SC_PAGESIZE
@@ -105,7 +107,7 @@
     }
 }
 
-    /// \brief close the open disk file and stream.
+/// \brief Close the open disk file and it's associated stream.
 void
 DiskStream::close()
 {
@@ -119,6 +121,8 @@
     _filespec.clear();
 }
 
+///  \brief Dump the internal data of this class in a human readable form.
+/// @remarks This should only be used for debugging purposes.
 void
 DiskStream::dump()
 {
@@ -141,7 +145,12 @@
 ///    This loads a pagesize of the disk file into memory. We read
 ///    the file this way as it is faster and takes less resources
 ///    than read(), which add buffering we don't need.
-///
+///    This offset must be a multipe of the pagesize.
+///
+/// @param size The location in bytes in the file of the desired data.
+///
+/// @return A real pointer to the location of the data at the
+///    location pointed to by the offset.
 boost::uint8_t *
 DiskStream::loadChunk(off_t offset)
 {
@@ -226,6 +235,12 @@
 #endif
 }
 
+/// \brief Open a file to be streamed.
+///
+/// @param filespec The full path and file name for the data to be
+///    read.
+///
+/// @return True if the file was opened sucessfully, false if not.
 bool
 DiskStream::open(const string &filespec)
 {
@@ -234,6 +249,14 @@
     return open(filespec, _netfd);
 }
 
+/// \brief Open a file to be streamed.
+///
+/// @param filespec The full path and file name for the data to be
+///    read.
+///
+/// @param netfd An optional file descriptor to read data from
+///
+/// @return True if the file was opened sucessfully, false if not.
 bool
 DiskStream::open(const string &filespec, int /*netfd*/)
 {
@@ -244,6 +267,17 @@
     return open(filespec, _netfd, _statistics);
 }
 
+/// \brief Open a file to be streamed.
+///
+/// @param filespec The full path and file name for the data to be
+///    read.
+///
+/// @param netfd An optional file descriptor to read data from
+///
+/// @param statistics The optional data structure to use for
+///    collecting statistics on this stream.
+///
+/// @return True if the file was opened sucessfully, false if not.
 bool
 DiskStream::open(const string &filespec, int netfd, Statistics &statistics)
 {
@@ -283,7 +317,9 @@
     return true;
 }
 
-// Stream the file
+/// \brief Stream the file that has been loaded,
+///
+/// @return True if the data was streamed sucessfully, false if not.
 bool
 DiskStream::play()
 {
@@ -292,6 +328,11 @@
     return play(_netfd);
 }
 
+/// \brief Stream the file that has been loaded,
+///
+/// @param netfd An optional file descriptor to read data from
+///
+/// @return True if the data was streamed sucessfully, false if not.
 bool
 DiskStream::play(int netfd)
 {
@@ -347,7 +388,17 @@
     return true;
 }
 
-// Stream a preview, instead of the full movie.
+/// \brief Stream a preview of the file.
+///    A preview is a series of video frames from
+///    the video file. Each video frame is taken by sampling
+///    the file at a set interval.
+///
+/// @param filespec The full path and file name for the data to be
+///    read.
+///
+/// @param quantity The number of frames to stream..
+///
+/// @return True if the thumbnails were streamed sucessfully, false if not.
 bool
 DiskStream::preview(const string & /*filespec*/, int /*frames*/)
 {
@@ -358,7 +409,17 @@
     return true; // Default to true    
 }
 
-// Stream a series of thumbnails
+/// \brief Stream a series of thumbnails.
+///    A thumbnail is a series of jpg images of frames from
+///    the video file instead of video frames. Each thumbnail
+///    is taken by sampling the file at a set interval.
+///
+/// @param filespec The full path and file name for the data to be
+///    read.
+///
+/// @param quantity The number of thumbnails to stream..
+///
+/// @return True if the thumbnails were streamed sucessfully, false if not.
 bool
 DiskStream::thumbnail(const string & /*filespec*/, int /*quantity*/)
 {
@@ -369,7 +430,9 @@
     return true; // Default to true
 }
 
-// Pause the stream
+/// \brief Pause the stream currently being played.
+///
+/// @return True if the stream was paused sucessfully, false if not.
 bool
 DiskStream::pause()
 {
@@ -380,7 +443,12 @@
     return true; // Default to true
 }
 
-// Seek within the stream
+/// \brief Seek within the stream.
+///
+/// @param the offset in bytes to the location within the file to
+///    seek to.
+///
+/// @return A real pointer to the location of the data seeked to.
 boost::uint8_t *
 DiskStream::seek(off_t offset)
 {
@@ -390,7 +458,15 @@
     return loadChunk(offset);    
 }
 
-// Upload a stream into a sandbox
+/// \brief Upload a file into a sandbox.
+///    The sandbox is an area where uploaded files can get
+///    written to safely. For SWF content, the file name also
+///    includes a few optional paths used to seperate
+///    applications from each other.
+///
+/// @param filespec The file name for the data to be written.
+///
+/// @return True if the file was uploaded sucessfully, false if not.
 bool
 DiskStream::upload(const string & /*filespec*/)
 {

=== modified file 'cygnal/diskstream.h'
--- a/cygnal/diskstream.h       2008-11-03 19:13:37 +0000
+++ b/cygnal/diskstream.h       2008-11-03 19:33:59 +0000
@@ -166,7 +166,6 @@
     void setPagesize(size_t size) { _pagesize = size; };
     
     ///  \brief Dump the internal data of this class in a human readable form.
-    ///
     /// @remarks This should only be used for debugging purposes.
      void dump();
 //    friend std::ostream& operator<< (std::ostream &os, const DiskStream &ds);