Documentation

- shifted namespace docs from modules -> namespaces for clarity.

Namespaces
- added namespace mp4v2::util::itmf iTunes Metadata Format.
- added namespace mp4v2::util::qtff QuickTime File Format.

Utilities
- mp4art now (finally) supports multiple cover-art data atoms
- mp4art, mp4file, mp4track and mp4subtitle updated:
    1. member-pointers instead of enums for actions.
    2. standard-options are now opt-in explicit, see the
       constructor for each utility.
    3. all short-syntax for actions are gone; actions are now
       long-syntax only; this makes things super-clear as it
       was a struggle to find short-syntax that made sense
       and did not conflict with standard options. thus,
       only standard options support both short/long syntax.

New Classes
- libutil/Timecode.h for future work on parsing time durations
  from strings; will be used for text file import/export.
- libutil/Database.h for key/value text file reading; will be
  used for text file import/export.

GNUmakefile.am

@@ -141,6 +141,10 @@ if ADD_PLATFORM_WIN32
 endif
 
 libutil_la_SOURCES = \
+    libutil/Database.h   \
+    libutil/Database.cpp \
+    libutil/Timecode.h   \
+    libutil/Timecode.cpp \
     libutil/Utility.h    \
     libutil/Utility.cpp  \
     libutil/crc.h        \
@@ -153,10 +157,14 @@ libutil_la_SOURCES = \
 if ADD_UTIL
     noinst_LTLIBRARIES += libutil.la
 
-    libmp4v2_la_SOURCES += \
-        src/libutil.h \
-        src/libutil.cpp \
-        src/subtitle.h \
+    libmp4v2_la_SOURCES +=  \
+        src/itmf.h          \
+        src/itmf.cpp        \
+        src/libutil.h       \
+        src/libutil.cpp     \
+        src/qtff.h          \
+        src/qtff.cpp        \
+        src/subtitle.h      \
         src/subtitle.cpp
 
     bin_PROGRAMS += mp4art

doc/doxygen/Doxyfile.m4

@@ -554,7 +554,13 @@ WARN_LOGFILE           =
 # directories like "/usr/src/myproject". Separate the files or directories 
 # with spaces.
 
-INPUT = __MAKE_ABS_TOP_SRCDIR/doc/doxygen/mainpage.h __MAKE_ABS_TOP_SRCDIR/include __MAKE_ABS_TOP_SRCDIR/libplatform __MAKE_ABS_TOP_SRCDIR/util/Utility.h
+INPUT = __MAKE_ABS_TOP_SRCDIR/doc/doxygen/mainpage.h \
+    __MAKE_ABS_TOP_SRCDIR/include \
+    __MAKE_ABS_TOP_SRCDIR/libplatform \
+    __MAKE_ABS_TOP_SRCDIR/src/libutil.h \
+    __MAKE_ABS_TOP_SRCDIR/src/itmf.h \
+    __MAKE_ABS_TOP_SRCDIR/src/qtff.h \
+    __MAKE_ABS_TOP_SRCDIR/util/Utility.h
 
 # This tag can be used to specify the character encoding of the source files 
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is 
@@ -897,7 +903,7 @@ DISABLE_INDEX          = NO
 # This tag can be used to set the number of enum values (range [1..20]) 
 # that doxygen will group on one line in the generated HTML documentation.
 
-ENUM_VALUES_PER_LINE   = 4
+ENUM_VALUES_PER_LINE   = 3
 
 # The GENERATE_TREEVIEW tag is used to specify whether a tree-like index
 # structure should be generated to display hierarchical information.

doc/doxygen/mainpage.h

@@ -1,8 +1,8 @@
 /** @mainpage MP4v2 API Reference
 
 The MP4v2 library provides an API to create and modify mp4 files as defined
-by ISO base media file format, document number ISO/IEC 14496-12:2005(E).
-It is a very powerful and extensible format that can accomodate practically
+by ISO base media file format, document number ISO/IEC 14496-12:2005(E). It
+is a very powerful and extensible format that can accomodate practically
 any type of media.
 
 The basic structure of an mp4 file is that the file is a container for one
@@ -29,8 +29,10 @@ etails.
 @section invocation Invocation
 
 The public libary API is defined in @c <mp4v2/mp4v2.h> which includes all the
-necessary dependent header files. You should never use any other header
-files from MP4v2 sources.
+necessary dependent header files. <b>You must never use any other header
+files</b> for public API. Using other header files or symbols which are
+not exported via the public API is expressly not supported and may change
+at any time without notice.
 
 The MP4v2 library can be used by either C or C++ programs. The calling
 convention is C but for convenience if C++ is used default function arguments

libplatform/io/File.h

@@ -4,17 +4,15 @@
 namespace mp4v2 { namespace platform { namespace io {
 
 ///////////////////////////////////////////////////////////////////////////////
-//!
-//! Base file interface.
-//!
-//! File abstracts basic file functionality that may apply to many types of
-//! files. All files are assumed to be 64-bit files unless built on a 32-bit
-//! platform which does not support 64-bit file offsets. The interface uses a
-//! signed 64-bit value which can help with filesize math, thus limiting
-//! actual file size to 63-bits, roughly 9.22 million TB.
-//!
-//! @ingroup platform_io
-//!
+///
+/// Base file interface.
+///
+/// File abstracts basic file functionality that may apply to many types of
+/// files. All files are assumed to be 64-bit files unless built on a 32-bit
+/// platform which does not support 64-bit file offsets. The interface uses a
+/// signed 64-bit value which can help with filesize math, thus limiting
+/// actual file size to 63-bits, roughly 9.22 million TB.
+///
 ///////////////////////////////////////////////////////////////////////////////
 class File
 {

libplatform/io/FileSystem.h

@@ -4,13 +4,11 @@
 namespace mp4v2 { namespace platform { namespace io {
 
 ///////////////////////////////////////////////////////////////////////////////
-//!
-//! General file-system abstraction.
-//!
-//! FileSystem abstracts operations on files and directories.
-//!
-//! @ingroup platform_io
-//!
+///
+/// General file-system abstraction.
+///
+/// FileSystem abstracts operations on files and directories.
+///
 ///////////////////////////////////////////////////////////////////////////////
 class FileSystem
 {

libplatform/platform.h

@@ -1,6 +1,21 @@
 #ifndef MP4V2_PLATFORM_PLATFORM_H
 #define MP4V2_PLATFORM_PLATFORM_H
 
+/// @namespace mp4v2::platform (private) Platform abstraction.
+/// <b>WARNING: THIS IS A PRIVATE NAMESPACE. NOT FOR PUBLIC CONSUMPTION.</b>
+///
+/// This namespace implements platform abstractions that are useful for
+/// keeping the code base portable.
+
+/// @namespace mp4v2::platform::io (private) I/O.
+/// <b>WARNING: THIS IS A PRIVATE NAMESPACE. NOT FOR PUBLIC CONSUMPTION.</b>
+
+/// @namespace mp4v2::platform::number (private) Number.
+/// <b>WARNING: THIS IS A PRIVATE NAMESPACE. NOT FOR PUBLIC CONSUMPTION.</b>
+
+/// @namespace mp4v2::platform::sys (private) System.
+/// <b>WARNING: THIS IS A PRIVATE NAMESPACE. NOT FOR PUBLIC CONSUMPTION.</b>
+
 ///////////////////////////////////////////////////////////////////////////////
 
 #if defined( _WIN32 )
@@ -14,7 +29,6 @@
 #include "libplatform/warning.h"
 #include "libplatform/endian.h"
 
-//! @defgroup platform_io libplatform I/O
 #include "libplatform/io/File.h"
 #include "libplatform/io/FileSystem.h"
 

libplatform/process/process.h

@@ -1,6 +1,8 @@
 #ifndef MP4V2_PLATFORM_PROCESS_PROCESS_H
 #define MP4V2_PLATFORM_PROCESS_PROCESS_H
 
+/// @namespace mp4v2::platform::process (private) Process.
+/// <b>WARNING: THIS IS A PRIVATE NAMESPACE. NOT FOR PUBLIC CONSUMPTION.</b>
 namespace mp4v2 { namespace platform { namespace process {
 
 ///////////////////////////////////////////////////////////////////////////////

libplatform/prog/option.h

@@ -1,26 +1,25 @@
 #ifndef MP4V2_PLATFORM_PROG_OPTION_H
 #define MP4V2_PLATFORM_PROG_OPTION_H
 
-namespace mp4v2 { namespace platform { namespace prog {
-
 ///////////////////////////////////////////////////////////////////////////////
-//!
-//! @defgroup platform_prog libplatform Program Option
-//! @{
-//!
-//! This module provides a mechanism to parse command-line arguments and
-//! options for executables.
-//! It is identical in behavior to <b>getopt_long</b> functions available
-//! with many popular posix-platforms such as Darwin, FreeBSD and Linux.
-//! Virtually any OS which has getopt_long will adequately document this
-//! functionality. However, to avoid symbol ambiguity with the popular
-//! posix implementation, the following identifiers have been renamed:
-//!     @li getopt_long()      -> getOption()
-//!     @li getopt_long_only() -> getOptionWord()
-//!     @li option             -> Option
-//!     @li option.has_arg     -> Option.type
+///
+/// @namespace mp4v2::platform::prog Command-line argument parsing.
+/// <b>WARNING: THIS IS A PRIVATE NAMESPACE. NOT FOR PUBLIC CONSUMPTION.</b>
+///
+/// This namespace provides a mechanism to parse command-line arguments and
+/// options for executables.
+/// It is identical in behavior to <b>getopt_long</b> functions available
+/// with many popular posix-platforms such as Darwin, FreeBSD and Linux.
+/// Virtually any OS which has getopt_long will adequately document this
+/// functionality. However, to avoid symbol ambiguity with the popular
+/// posix implementation, the following identifiers have been renamed:
+///     @li getopt_long()      -> getOption()
+///     @li getopt_long_only() -> getOptionSingle()
+///     @li option             -> Option
+///     @li option.has_arg     -> Option.type
 //!
 ///////////////////////////////////////////////////////////////////////////////
+namespace mp4v2 { namespace platform { namespace prog {
 
 //! On return from getOption() or getOptionSingle(),
 //! points to an option argument, if it is anticipated.
@@ -166,8 +165,6 @@ int getOption( int argc, char* const* argv, const char* optstr, const Option* lo
 ///////////////////////////////////////////////////////////////////////////////
 int getOptionSingle( int argc, char* const* argv, const char* optstr, const Option* longopts, int* idx );
 
-///////////////////////////////////////////////////////////////////////////////
-//! @}
 ///////////////////////////////////////////////////////////////////////////////
 
 }}} // namespace mp4v2::platform::prog

libplatform/time/time.h

@@ -1,13 +1,10 @@
 #ifndef MP4V2_PLATFORM_TIME_TIME_H
 #define MP4V2_PLATFORM_TIME_TIME_H
 
+/// @namespace mp4v2::platform::time (private) Time.
+/// <b>WARNING: THIS IS A PRIVATE NAMESPACE. NOT FOR PUBLIC CONSUMPTION.</b>
 namespace mp4v2 { namespace platform { namespace time {
 
-///////////////////////////////////////////////////////////////////////////////
-//! @defgroup platform_time libplatform Time
-//! @{
-///////////////////////////////////////////////////////////////////////////////
-
 //! type used to represent milliseconds
 typedef int64_t milliseconds_t;