Documentation update.

src/common/chapters.cpp

@@ -167,8 +167,8 @@ probe_simple_chapters(mm_text_io_c *in) {
  *   end timecodes after the timerange check has been made.
  * \param language This language is added as the \c KaxChapterLanguage
  *   for all entries.
- * \param country This country is added as the \c KaxChapterCountry for
+ * \param charset The charset the chapters are supposed to be it. The entries
- *   all entries.
+ *   will be converted to UTF-8 if necessary.
  * \param exception_on_error If set to \c true then an exception is thrown
  *   if an error occurs. Otherwise \c NULL will be returned.
  *
@@ -307,13 +307,35 @@ parse_simple_chapters(mm_text_io_c *in,
 /** \brief Probe a file for different chapter formats and parse the file.
  *
  * The file \a file_name is opened and checked for supported chapter formats.
+ * These include simple OGM style chapters, CUE sheets and mkvtoolnix' own
+ * XML chapter format.
  *
  * Its parameters don't have to be checked for validity.
  *
- * \see ::parse_chapters(mm_text_io_c *in,int64_t min_tc,int64_t max_tc, int64_t offset,const string &language,const string &charset,bool exception_on_error,bool *is_simple_format,KaxTags **tags)
+ * \param file_name The name of the text file to read from.
- * for a full description of its parameters and return values.
+ * \param min_tc An optional timecode. If both \a min_tc and \a max_tc are
+ *   given then only those chapters that lie in the timerange
+ *   <tt>[min_tc..max_tc]</tt> are kept.
+ * \param max_tc An optional timecode. If both \a min_tc and \a max_tc are
+ *   given then only those chapters that lie in the timerange
+ *   <tt>[min_tc..max_tc]</tt> are kept.
+ * \param offset An optional offset that is subtracted from all start and
+ *   end timecodes after the timerange check has been made.
+ * \param language This language is added as the \c KaxChapterLanguage
+ *   for entries that don't specifiy it.
+ * \param charset The charset the chapters are supposed to be it. The entries
+ *   will be converted to UTF-8 if necessary. This parameter is ignored for XML
+ *   chapter files.
+ * \param exception_on_error If set to \c true then an exception is thrown
+ *   if an error occurs. Otherwise \c NULL will be returned.
+ * \param is_simple_format This boolean will be set to \c true if the chapter
+ *   format is either the OGM style format or a CUE sheet.
+ * \param tags When parsing a CUE sheet tags will be created along with the
+ *   chapter entries. These tags will be stored in this parameter.
  *
- * \param file_name The file name that is to be opened.
+ * \return The chapters parsed from the file or \c NULL if an error occured.
+ *
+ * \see ::parse_chapters(mm_text_io_c *in,int64_t min_tc,int64_t max_tc, int64_t offset,const string &language,const string &charset,bool exception_on_error,bool *is_simple_format,KaxTags **tags)
  */
 KaxChapters *
 parse_chapters(const string &file_name,
@@ -367,8 +389,9 @@ parse_chapters(const string &file_name,
  *   end timecodes after the timerange check has been made.
  * \param language This language is added as the \c KaxChapterLanguage
  *   for entries that don't specifiy it.
- * \param country This country is added as the \c KaxChapterCountry for
+ * \param charset The charset the chapters are supposed to be it. The entries
- *   entries that don't specifiy it.
+ *   will be converted to UTF-8 if necessary. This parameter is ignored for XML
+ *   chapter files.
  * \param exception_on_error If set to \c true then an exception is thrown
  *   if an error occurs. Otherwise \c NULL will be returned.
  * \param is_simple_format This boolean will be set to \c true if the chapter
@@ -488,8 +511,8 @@ get_chapter_uid(KaxChapterAtom &atom) {
  * The Matroska specs and \c libmatroska say that several elements are
  * mandatory. This function makes sure that they all exist by adding them
  * with their default values if they're missing. It works recursively. See
- * \url http://www.matroska.org/technical/specs/chapters/index.html
+ * <a href="http://www.matroska.org/technical/specs/chapters/index.html">
- * for a list or mandatory elements.
+ * the Matroska chapter specs</a> for a list or mandatory elements.
  *
  * The parameters are checked for validity.
  *

src/common/mm_io.cpp

@@ -943,7 +943,7 @@ mm_text_io_c::get_byte_order() {
 }
 
 void
-mm_text_io_c::setFilePointer(int64_t offset,
+mm_text_io_c::setFilePointer(int64 offset,
                              seek_mode mode) {
   if ((offset == 0) && (mode == seek_beginning))
     mm_proxy_io_c::setFilePointer(bom_len, seek_beginning);

src/common/mpeg4_common.cpp

@@ -1,4 +1,5 @@
 /** MPEG video helper functions (MPEG 1, 2 and 4)
+ *
  * mkvmerge -- utility for splicing together matroska files
  * from component media subtypes
  *
@@ -110,10 +111,10 @@ mpeg4_extract_par(const unsigned char *buffer,
  *   a dummy frame) then \a frames will contain no elements.
  */
 void
-mpeg4_find_frame_types(const unsigned char *buf,
+mpeg4_find_frame_types(const unsigned char *buffer,
                        int size,
                        vector<video_frame_t> &frames) {
-  bit_cursor_c bits(buf, size);
+  bit_cursor_c bits(buffer, size);
   uint32_t marker, frame_type;
   bool first_frame;
   video_frame_t frame;

src/common/mpeg4_common.h

@@ -1,4 +1,5 @@
-/*
+/** MPEG video helper functions (MPEG 1, 2 and 4)
+ *
  * mkvmerge -- utility for splicing together matroska files
  * from component media subtypes
  *
@@ -6,11 +7,10 @@
  * see the file COPYING for details
  * or visit http://www.gnu.org/copyleft/gpl.html
  *
- * $Id$
+ * \file
+ * \version $Id$
  *
- * MPEG1, 2 and 4 video helper functions
+ * \author Written by Moritz Bunkus <moritz@bunkus.org>.
- *
- * Written by Moritz Bunkus <moritz@bunkus.org>.
  */
 
 #ifndef __MPEG4_COMMON_H
@@ -38,17 +38,44 @@
 /** MPEG-1/-2 frame rate: 60 frames per second */
 #define MPEGVIDEO_FPS_60        0x08
 
+/** Pointers to MPEG4 video frames and their data
+ *
+ * MPEG4 video can be stored in a "packed" format, e.g. in AVI. This means
+ * that one AVI chunk may contain more than one video frame. This is
+ * usually the case with B frames due to limitations in how AVI and
+ * Windows' media frameworks work. With ::mpeg4_find_frame_types
+ * such packed frames can be analyzed. The results are stored in these
+ * structures: one structure for one frame in the analyzed chunk.
+ */
 typedef struct {
+  /** The beginning of the frame data. This is a pointer into an existing
+      buffer handed over to ::mpeg4_find_frame_types. */
   unsigned char *data;
-  int size, pos;
+  /** The size of the frame in bytes. */
+  int size;
+  /** The position of the frame in the original buffer. */
+  int pos;
+  /** The frame type: \c 'I', \c 'P' or \c 'B'. */
   char type;
+  /** Private data. */
   unsigned char *priv;
-  int64_t timecode, duration, bref, fref;
+  /** The timecode of the frame in \c ns. */
+  int64_t timecode;
+  /** The duration of the frame in \c ns. */
+  int64_t duration;
+  /** The frame's backward reference in \c ns relative to its
+      \link video_frame_t::timecode timecode \endlink.
+      This value is only set for P and B frames. */
+  int64_t bref;
+  /** The frame's forward reference in \c ns relative to its
+      \link video_frame_t::timecode timecode \endlink.
+      This value is only set for B frames. */
+  int64_t fref;
 } video_frame_t;
 
 bool MTX_DLL_API mpeg4_extract_par(const unsigned char *buffer, int size,
                                    uint32_t &par_num, uint32_t &par_den);
-void MTX_DLL_API mpeg4_find_frame_types(const unsigned char *buf, int size,
+void MTX_DLL_API mpeg4_find_frame_types(const unsigned char *buffer, int size,
                                         vector<video_frame_t> &frames);
 
 int MTX_DLL_API mpeg1_2_extract_fps_idx(const unsigned char *buffer,