upgrade to XMP-SDK 4.4.2

16 files changed, 3837 insertions, 2768 deletions

diff --git a/public/include/TXMPFiles.hpp b/public/include/TXMPFiles.hpp
index 499dfb9..00c0b7d 100644
--- a/public/include/TXMPFiles.hpp
+++ b/public/include/TXMPFiles.hpp
@@ -14,393 +14,610 @@
 // of the Adobe license agreement accompanying it.
 // =================================================================================================
 
-//  ================================================================================================
+// =================================================================================================
 /// \file TXMPFiles.hpp
-/// \brief API for access to the "main" metadata in a file.
+/// \brief API for access to the main (document-level) metadata in a file_.
 ///
-/// \c TXMPFiles provides the API for the Adobe XMP Toolkit's File Handler component. This provides
-/// convenient access to the main, or document level, XMP for a file. The File Handler supports file
-/// I/O, the XMP Toolkit Core supports manipulation of the XMP properties. The File Handler is
-/// intended to eventually have smart, efficient support for all file formats for which the means to
-/// embed XMP is defined in the XMP Specification. Where possible this support will allow injection
-/// of XMP where none currently exists, expansion of XMP without regard to existing padding, and
-/// reconciliation of the XMP and other legacy forms of metadata.
+/// The Adobe XMP Toolkit's file handling component, XMPFiles, is a front end to a set of
+/// format-specific file handlers that support file I/O for XMP. The file handlers implement smart,
+/// efficient support for those file formats for which the means to embed XMP is defined in the XMP
+/// Specification. Where possible, this support allows:
+///   \li Injection	of XMP where none currently exists
+///   \li Expansion of XMP without regard to existing padding
+///   \li Reconciliation of the XMP and other legacy forms of metadata.
 ///
-///\c  TXMPFiles is designed for use by clients interested in the metadata and not in the primary file
-/// content. The Adobe Bridge application is a typical example. \c TXMPFiles is not intended to be
-/// particulary appropriate for files authored by an application. I.e. those files for which the
+/// \c TXMPFiles is designed for use by clients interested in the metadata and not in the primary
+/// file content; the Adobe Bridge application is a typical example. \c TXMPFiles is not intended to
+/// be appropriate for files authored by an application; that is, those files for which the
 /// application has explicit knowledge of the file format.
-//  ================================================================================================
+// =================================================================================================
+
 
-//  ================================================================================================
+// =================================================================================================
 /// \class TXMPFiles TXMPFiles.hpp
-/// \brief API for access to the "main" metadata in a file.
+/// \brief API for access to the main (document-level) metadata in a file.
+///
+/// \c TXMPFiles is a template class that provides the API for the Adobe XMP Toolkit's XMPFiles
+/// component. This provides convenient access to the main, or document level, XMP for a file. Use
+/// it to obtain metadata from a file, which you can then manipulate with the XMP Core component
+/// (the classes \c TXMPMeta, \c TXMPUtils, and \c TXMPIterator); and to write new or changed
+/// metadata back out to a file.
 ///
-/// \c TXMPFiles provides the API for the Adobe XMP Toolkit's File Handler component. This provides
-/// convenient access to the main, or document level, XMP for a file. The general model is to open
-/// a file, read and write the metadata, then close the file. While open, portions of the file
-/// might be maintained in RAM data structures. Memory usage can vary considerably depending on
-/// file format and access options. The file may be opened for read-only or read-write access, with
-/// typical exclusion for both modes.
+/// The functions allow you to open a file, read and write the metadata, then close the file.
+/// While open, portions of the file might be maintained in RAM data structures. Memory
+/// usage can vary considerably depending onfile format and access options.
 ///
-/// Errors result in the throw of an \c XMPError exception.
+/// A file can be opened for read-only or read-write access, with typical exclusion for both
+/// modes. Errors result in the throw of an \c XMPError exception.
 ///
-/// The template is instantiated with a string object class. This allows a clean implementation
-/// that provides two major benefits: output string storage is fully owned by the client and access
-/// is fully thread safe. The template parameter, class \c tStringObj, is described in the XMP.hpp
-/// umbrella header.
+/// \c TXMPFiles is the template class. It must be instantiated with a string class such as
+/// \c std::string. Read the Toolkit Overview for information about the overall architecture of the XMP
+/// API, and the documentation for \c XMP.hpp for specific instantiation instructions.
 ///
-/// To use TXMPFiles define TXMP_STRING_TYPE and XMP_INCLUDE_XMPFILES, then include the XMP.hpp 
-/// umbrella header:
-/// \code
-///  #define TXMP_STRING_TYPE std::string
-///  #define XMP_INCLUDE_XMPFILES 1
-///  #include "XMP.hpp"
-/// \endcode
-//  ================================================================================================
+/// Access these functions through the concrete class, \c SXMPFiles.
+// =================================================================================================
+
 
 template <class tStringObj>
 class TXMPFiles {
 
 public:
-	
-	//  ============================================================================================
+
+	// =============================================================================================
     /// \name Initialization and termination
     /// @{
-    /// \c SXMPFiles must be initialized before use and may be terminated when done.
+    ///
+    /// A \c TXMPFiles object must be initialized before use and can be terminated when done.
+
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c GetVersionInfo() retrieves version information for the XMPFiles component.
+    ///
+    /// Can be called before \c #Initialize(). This function is static; make the call directly from
+    /// the concrete class (\c SXMPFiles).
+    ///
+    /// @param versionInfo [out] A buffer in which to return the version information.
 
     static void GetVersionInfo ( XMP_VersionInfo * versionInfo );
 
-	/// \brief \c Initialize must be called before using \c SXMPFiles. It returns a Boolean 
-	/// success/failure value.
-	
+    // ---------------------------------------------------------------------------------------------
+    /// @brief Initializes the XMPFiles library; must be called before creating an \c SXMPFiles object.
+    ///
+    /// The main action is to activate the available smart file handlers. Must be called before
+    /// using any methods except \c GetVersionInfo().
+    ///
+    /// This function is static; make the call directly from the concrete class (\c SXMPFiles).
+    ///
+    /// @return True on success.
+
 	static bool Initialize();
+
+    // ---------------------------------------------------------------------------------------------
+    /// @brief Initializes the XMPFiles library; must be called before creating an \c SXMPFiles object.
+    ///
+    /// This overload of TXMPFiles::Initialize() accepts option bits to customize the initialization
+    /// actions. At this time only one option is defined, \c kXMPFiles_NoQuickTimeInit. This option
+    /// prevents calling the QuickTime initialization on Windows, which can be slow. The MOV file
+    /// handler on Windows uses Apple's QuickTime SDK for the actual file I/O.
+    ///
+    /// The main action is to activate the available smart file handlers. Must be called before
+    /// using any methods except \c GetVersionInfo().
+    ///
+    /// This function is static; make the call directly from the concrete class (\c SXMPFiles).
+    ///
+    /// @param options Option flags to control the initialization actions.
+    ///
+    /// @return True on success.
+
 	static bool Initialize ( XMP_OptionBits options );
 
-	/// \brief \c Terminate may be called when done using \c SXMPFiles. It deallocates global data
-	/// structures created by \c Initialize.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief Terminates use of the XMPFiles library.
+    ///
+    /// Optional. Deallocates global data structures created by intialization. Its main action is to
+    /// deallocate heap-allocated global storage, for the benefit of client leak checkers.
+    ///
+    /// This function is static; make the call directly from the concrete class (\c SXMPFiles).
 
 	static void Terminate();
 
     /// @}
 
-	//  ============================================================================================
+	// =============================================================================================
     /// \name Constructors and destructor
     /// @{
+    ///
     /// The default constructor initializes an object that is associated with no file. The alternate
-    /// constructors call OpenFile. The destructor automatically calls CloseFile if necessary.
-    
-    /// \brief The default constructor initializes an object that is associated with no file.
-    
+    /// constructors call \c OpenFile().
+
+    // ---------------------------------------------------------------------------------------------
+    /// @brief Default constructor initializes an object that is associated with no file.
+
     TXMPFiles();
+
+    // ---------------------------------------------------------------------------------------------
+    /// @brief Destructor; typical virtual destructor.
+    ///
+    /// The destructor does not call \c CloseFile(); pending updates are lost when the destructor is run.
+    ///
+    /// @see \c OpenFile(), \c CloseFile()
+
 	virtual ~TXMPFiles() throw();
 
-    /// \brief These alternate constructors call \c OpenFile. The second form is a trivial overload
-    /// that calls the first form passing \c filePath.c_str().
-    
+    // ---------------------------------------------------------------------------------------------
+    /// @brief Alternate constructor associates the new \c XMPFiles object with a specific file.
+    ///
+    /// Calls \c OpenFile() to open the specified file after performing a default construct.
+    ///
+    /// @param filePath	The path for the file, specified as a nul-terminated UTF-8 string.
+    ///
+    /// @param format A format hint for the file, if known.
+    ///
+    /// @param openFlags Options for how the file is to be opened (for read or read/write, for
+    /// example). Use a logical OR of these bit-flag constants:
+    ///
+    ///   \li \c #kXMPFiles_OpenForRead
+    ///   \li \c #kXMPFiles_OpenForUpdate
+    ///   \li \c #kXMPFiles_OpenOnlyXMP
+    ///   \li \c #kXMPFiles_OpenCacheTNail
+    ///   \li \c #kXMPFiles_OpenStrictly
+    ///   \li \c #kXMPFiles_OpenUseSmartHandler
+    ///   \li \c #kXMPFiles_OpenUsePacketScanning
+    ///   \li \c #kXMPFiles_OpenLimitedScanning
+    ///   \li \c #kXMPFiles_OpenInBackground
+    ///
+    /// @return The new \c TXMPFiles object.
+
     TXMPFiles ( XMP_StringPtr  filePath,
 				XMP_FileFormat format = kXMP_UnknownFile,
 				XMP_OptionBits openFlags = 0 );
 
+    // ---------------------------------------------------------------------------------------------
+    /// @brief Alternate constructor associates the new \c XMPFiles object with a specific file,
+    /// using a string object.
+    ///
+    /// Overloads the basic form of the function, allowing you to pass a string object
+	/// for the file path. It is otherwise identical; see details in the canonical form.
+
     TXMPFiles ( const tStringObj & filePath,
 				XMP_FileFormat     format = kXMP_UnknownFile,
 				XMP_OptionBits     openFlags = 0 );
 
-	/// \brief The copy constructor and assignment operator increment an internal reference count,
-	/// they do not perform a deep copy.
-	
+    // ---------------------------------------------------------------------------------------------
+    /// @brief Copy constructor
+    ///
+    /// Increments an internal reference count but does not perform a deep copy.
+    ///
+    /// @param original The existing \c TXMPFiles object to copy.
+    ///
+    /// @return The new \c TXMPFiles object.
+
     TXMPFiles ( const TXMPFiles<tStringObj> & original );
 
+    // ---------------------------------------------------------------------------------------------
+    /// @brief Assignment operator
+    ///
+    /// Increments an internal reference count but does not perform a deep copy.
+    ///
+    /// @param rhs The existing \c TXMPFiles object.
+
 	void operator= ( const TXMPFiles<tStringObj> & rhs );
 
-	/// \brief The "ref" constructor and \c GetInternalRef serve the same purpose as their analogs
-	/// in SXMPMeta, safely passing \c SXMPFiles references across DLL boundaries where the clients
-	/// might have used different string types when instantiating \c TXMPFiles.
-	
+    // ---------------------------------------------------------------------------------------------
+    /// @brief Reconstructs a \c TXMPFiles object from an internal reference.
+    ///
+    /// This constructor creates a new \c TXMPFiles object that refers to the underlying reference
+    /// object of an existing \c TXMPFiles object. Use to safely pass \c SXMPFiles references across
+    /// DLL boundaries.
+    ///
+    /// @param xmpFilesObj The underlying reference object, obtained from some other XMP object
+    /// with \c TXMPFiles::GetInternalRef().
+    ///
+    /// @return The new object.
+
     TXMPFiles ( XMPFilesRef xmpFilesObj );
-    
+
+    // ---------------------------------------------------------------------------------------------
+    /// @brief GetInternalRef() retrieves an internal reference that can be safely passed across DLL
+    /// boundaries and reconstructed.
+    ///
+    /// Use with the reconstruction constructor to safely pass \c SXMPFiles references across DLL
+    /// boundaries where the clients might have used different string types when instantiating
+    /// \c TXMPFiles.
+	///
+    /// @return The internal reference.
+    ///
+    /// @see \c TXMPMeta::GetInternalRef() for usage.
+
     XMPFilesRef GetInternalRef();
 
     /// @}
-	
-	//  ============================================================================================
-    /// \name Static Functions
+
+	// =============================================================================================
+    /// \name File handler information
     /// @{
-    
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Determine the supported features for a given file format.
     ///
-    /// The supported features can vary quite a bit among file formats, depending on both the
-    /// general capabilities of the format and the implementation of the handler for that format.
+    /// Call this static function from the concrete class, \c SXMPFiles, to obtain information about
+    /// the file handlers for the XMPFiles component.
+
+    // ---------------------------------------------------------------------------------------------
+    /// @brief  GetFormatInfo() reports what features are supported for a specific file format.
+    ///
+    /// The file handlers for different file formats vary considerably in what features they
+    /// support. Support depends on both the general capabilities of the format and the
+    /// implementation of the handler for that format.
     ///
-    /// \param format The format whose support flags are desired.
+    ///This function is static; make the call directly from the concrete class (\c SXMPFiles).
     ///
-    /// \param handlerFlags A set of option bits showing the support for this format:
+    /// @param format The file format whose support flags are desired.
     ///
-    /// \li kXMPFiles_CanInjectXMP - Can inject first-time XMP into an existing file.
-    /// \li kXMPFiles_CanExpand - Can expand XMP or other metadata in an existing file.
-    /// \li kXMPFiles_CanRewrite - Can copy one file to another, writing new metadata.
-    /// \li kXMPFiles_CanReconcile - Supports reconciliation between XMP and other forms.
-    /// \li kXMPFiles_AllowsOnlyXMP - Allows access to just the XMP, ignoring other forms.
-    /// \li kXMPFiles_ReturnsRawPacket - File handler returns raw XMP packet information and string.
-    /// \li kXMPFiles_ReturnsTNail - File handler returns native thumbnail information.
+    /// @param handlerFlags [out] A buffer in which to return a logical OR of option bit flags.
+    /// The following constants are defined:
     ///
-    /// The kXMPFiles_AllowsOnlyXMP flag is only meaningful if kXMPFiles_CanReconcile is set.
+    ///   \li \c #kXMPFiles_CanInjectXMP - Can inject first-time XMP into an existing file.
+    ///   \li \c #kXMPFiles_CanExpand - Can expand XMP or other metadata in an existing file.
+    ///   \li \c #kXMPFiles_CanRewrite - Can copy one file to another, writing new metadata (as in SaveAs)
+    ///   \li \c #kXMPFiles_CanReconcile - Supports reconciliation between XMP and other forms.
+    ///   \li \c #kXMPFiles_AllowsOnlyXMP - Allows access to just the XMP, ignoring other forms.
+    ///   This is only meaningful if \c #kXMPFiles_CanReconcile is set.
+    ///   \li \c #kXMPFiles_ReturnsTNail - File handler returns native thumbnail information.
+    ///   \li \c #kXMPFiles_ReturnsRawPacket - File handler returns raw XMP packet information and string.
     ///
-    /// If kXMPFiles_ReturnsRawPacket is set, the returned packet information might have an offset
-    /// of -1 to indicate an unknown offset. While all file handlers should be able to return the
-    /// raw packet, some might not know the offset of the packet within the file. This is typical
-    /// in cases where external libraries are used. These cases might not even allow return of the
-    /// raw packet.
+    /// Even if \c #kXMPFiles_ReturnsRawPacket is set, the returned packet information might have an
+    /// offset of -1 to indicate an unknown offset. While all file handlers should be able to return
+    /// the raw packet, some might not know the offset of the packet within the file. This is
+    /// typical in cases where external libraries are used. These cases might not even allow return
+    /// of the raw packet.
     ///
-    /// \result Returns true if the format has explicit "smart" support. Returns false if the format
-    /// is handled by the default packet scanning plus heuristics.
-    
+    /// @return True if the format has explicit "smart" support, false if the format is handled by
+    /// the default packet scanning plus heuristics. */
+
+
     static bool GetFormatInfo ( XMP_FileFormat   format,
     							XMP_OptionBits * handlerFlags = 0 );
 
     /// @}
-	
-	//  ============================================================================================
-    /// \name OpenFile, CloseFile, and related file-oriented operations
+
+	// =============================================================================================
+    /// \name File operations
     /// @{
-	
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Open a file for metadata access.
+    ///
+    /// These functions allow you to open, close, and query files.
+
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c CheckFileFormat() tries to determine the format of a file.
+    ///
+    /// \c CheckFileFormat tries to determine the format of a file, returning an XMP_FileFormat value.
+    /// It uses the same logic as \c OpenFile will use to select a smart handler.
+    ///
+    /// @param filePath The path for the file, appropriate for the local operating system. Passed as
+    /// a nul-terminated UTF-8 string. The path is the same as would be passed to \c OpenFile.
+    ///
+    /// @return The file's format if a smart handler would be selected, otherwise \c kXMP_UnknownFile.
+
+    static XMP_FileFormat CheckFileFormat ( XMP_StringPtr filePath );
+
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c CheckPackageFormat() tries to determine the format of a "package" folder.
+    ///
+    /// \c CheckPackageFormat tries to determine the format of a "package" given the name of the top
+    /// level folder, returning an XMP_FileFormat value. Examples of recognized packages include the
+    /// video formats P2, XDCAM, or Sony HDV. These packages contain collections of "clips", stored
+    /// as multiple files in specific subfolders.
+    ///
+    /// @param folderPath The path for the top level folder, appropriate for the local operating
+    /// system. Passed as a nul-terminated UTF-8 string. The path is not the same as would be passed
+    /// to \c OpenFile. For example the path passed to \c CheckPackageFormat might be ".../MyMovie",
+    /// while the path passed to \c OpenFile would be ".../MyMovie/SomeClip".
+    ///
+    /// @return The package's format if a smart handler would be selected, otherwise \c kXMP_UnknownFile.
+    
+    static XMP_FileFormat CheckPackageFormat ( XMP_StringPtr folderPath );
+
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c OpenFile() opens a file for metadata access.
     ///
     /// Opens a file for the requested forms of metadata access. Opening the file at a minimum
     /// causes the raw XMP packet to be read from the file. If the file handler supports legacy
-    /// metadata reconciliation then legacy metadata will also be read, unless kXMPFiles_OpenOnlyXMP
-    /// is passed. If the file handler supports native thumbnails and kXMPFiles_OpenCacheTNail is
-    /// passed then the native thumbnail will also be cached.
-    ///
-    /// If the file is opened for read-only access (passing kXMPFiles_OpenForRead), then the disk
-    /// file itself will be closed after reading the data from it. The XMPFiles object will not be
-    /// "closed" though, it is still necessary to call CloseFile when finished using it. Other
-    /// methods (GetXMP, etc.) can only be used between the OpenFile and CloseFile calls. The XMPFiles
-    /// destructor will not call CloseFile, any pending updates will be lost.
-    ///
-    /// If the file is opened for update (passing kXMPFiles_OpenForUpdate), then the disk file remains
-    /// open until CloseFile is called. The disk file is only updated once, when Close file is called,
-    /// no matter how many calls are made to PutXMP.
-    ///
-    /// Ideally the XMP is not parsed and legacy reconciliation is not performed until GetXMP is
-    /// called. This is not guaranteed though, specific file handlers might do earlier parsing of
-    /// the XMP. This delayed parsing and the early disk file close for read-only access are
-    /// optimizations to help clients implementing file browsers. They can access the file briefly
+    /// metadata reconciliation then legacy metadata is also read, unless \c #kXMPFiles_OpenOnlyXMP
+    /// is passed. If the file handler supports native thumbnails and \c #kXMPFiles_OpenCacheTNail
+    /// is passed, the native thumbnail is cached.
+    ///
+    /// If the file is opened for read-only access (passing \c #kXMPFiles_OpenForRead), the disk
+    /// file is closed immediately after reading the data from it; the \c XMPFiles object, however,
+    /// remains in the open state. You must call \c CloseFile() when finished using it. Other
+    /// methods, such as \c GetXMP(), can only be used between the \c OpenFile() and \c CloseFile()
+    /// calls. The \c XMPFiles destructor does not call \c CloseFile(); if you call it without
+    /// closing, any pending updates are lost.
+    ///
+    /// If the file is opened for update (passing \c #kXMPFiles_OpenForUpdate), the disk file
+    /// remains open until \c CloseFile() is called. The disk file is only updated once, when
+    /// \c CloseFile() is called, regardless of how many calls are made to \c PutXMP().
+    ///
+    /// Typically, the XMP is not parsed and legacy reconciliation is not performed until \c GetXMP()
+    /// is called, but this is not guaranteed. Specific file handlers might do earlier parsing of
+    /// the XMP. Delayed parsing and early disk file close for read-only access are optimizations
+    /// to help clients implementing file browsers, so that they can access the file briefly
     /// and possibly display a thumbnail, then postpone more expensive XMP processing until later.
     ///
-    /// \param filePath The UTF-8 path for the file, appropriate for the local OS. Overloads are
-    /// declared to pass the path as either a "const char *" or a string object.
-    ///
-    /// \param format The format of the file. If the format is unknown pass \c kXMP_UnknownFile and
-    /// the format will be determined from the file content. The first handler to check will be
-    /// guessed from the file's extension. Passing any other format value is generally just a hint
-    /// about what file handler to try first (instead of the one based on the extension). If the 
-    /// kXMPFiles_OpenStrictly is set, then any format other than kXMP_UnknownFile requires that the
-    /// file actually be that format, an exception is thrown if not.
-    ///
-    /// \param openFlags A set of option bits describing the desired access. By default (zero) the
-    /// file is opened for read-only access and the format handler decides on the level of
-    /// reconciliation that will be performed. By default a best effort will be made to locate the
-    /// correct XMP and to reconcile XMP with other forms (if reconciliation is done). The option
-    /// \c kXMPFiles_OpenStrictly may be used to force more strict rules, resulting is exceptions for
-    /// errors. The definition of strictness is specific to each handler, there may be no difference.
-    ///
-    /// The defined openFlag bits are:
-    ///
-    /// \li kXMPFiles_OpenForRead - Open for read-only access.
-    /// \li kXMPFiles_OpenForUpdate - Open for reading and writing.
-    /// \li kXMPFiles_OpenOnlyXMP - Only the XMP is wanted, no reconciliation.
-    /// \li kXMPFiles_OpenCacheTNail - Cache thumbnail if possible, GetThumbnail will be called.
-    /// \li kXMPFiles_OpenStrictly - Be strict about locating XMP and reconciling with other forms.
-    /// \li kXMPFiles_OpenUseSmartHandler - Require the use of a smart handler.
-    /// \li kXMPFiles_OpenUsePacketScanning - Force packet scanning, don't use a smart handler.
-    ///
-    /// \result Returns true if the file is succesfully opened and attached to a file handler.
-    /// Returns false for "anticipated" problems, e.g. passing kXMPFiles_OpenUseSmartHandler but not
-    /// having an appropriate smart handler. Throws an exception for serious problems.
+    /// @param filePath The path for the file, appropriate for the local operating system. Passed as
+    /// a nul-terminated UTF-8 string.
+    ///
+    /// @param format The format of the file. If the format is unknown (\c #kXMP_UnknownFile) the
+    /// format is determined from the file content. The first handler to check is guessed from the
+    /// file's extension. Passing a specific format value is generally just a hint about what file
+    /// handler to try first (instead of the one based on the extension). If
+    /// \c #kXMPFiles_OpenStrictly is set, then any format other than \c #kXMP_UnknownFile requires
+    /// that the file actually be that format; otherwise an exception is thrown.
+    ///
+    /// @param openFlags A set of option flags that describe the desired access. By default (zero)
+    /// the file is opened for read-only access and the format handler decides on the level of
+    /// reconciliation that will be performed. A logical OR of these bit-flag constants:
+    ///
+    ///   \li \c #kXMPFiles_OpenForRead - Open for read-only access.
+    ///   \li \c #kXMPFiles_OpenForUpdate - Open for reading and writing.
+    ///   \li \c #kXMPFiles_OpenOnlyXMP - Only the XMP is wanted, no reconciliation.
+    ///   \li \c #kXMPFiles_OpenCacheTNail - Cache thumbnail if possible, GetThumbnail will be called.
+    ///   \li \c #kXMPFiles_OpenStrictly - Be strict about locating XMP and reconciling with other
+    ///   forms. By default, a best effort is made to locate the	correct XMP and to reconcile XMP
+    ///   with other forms (if reconciliation is done). This option forces stricter rules, resulting
+    ///   in exceptions for errors. The definition of strictness is specific to each handler, there
+    ///   might be no difference.
+    ///   \li \c #kXMPFiles_OpenUseSmartHandler - Require the use of a smart handler.
+    ///   \li \c #kXMPFiles_OpenUsePacketScanning - Force packet scanning, do not use a smart handler.
+    ///
+    /// @return True if the file is succesfully opened and attached to a file handler. False for
+    /// anticipated problems, such as passing \c #kXMPFiles_OpenUseSmartHandler but not having an
+    /// appropriate smart handler. Throws an exception for serious problems.
+
 
 	bool OpenFile ( XMP_StringPtr  filePath,
 				    XMP_FileFormat format = kXMP_UnknownFile,
 				    XMP_OptionBits openFlags = 0 );
-	
+
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c OpenFile() opens a file for metadata access, using a string object
+    ///
+    /// Overloads the basic form of the function, allowing you to pass a string object
+	/// for the file path. It is otherwise identical; see details in the canonical form.
+
 	bool OpenFile ( const tStringObj & filePath,
 				    XMP_FileFormat     format = kXMP_UnknownFile,
 				    XMP_OptionBits     openFlags = 0 );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Close an opened file.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief CloseFile() explicitly closes an opened file.
     ///
     /// Performs any necessary output to the file and closes it. Files that are opened for update
     /// are written to only when closing.
     ///
-    /// \param closeFlags A set of bit flags for optional closing actions.
+    /// If the file is opened for read-only access (passing \c #kXMPFiles_OpenForRead), the disk
+    /// file is closed immediately after reading the data from it; the \c XMPFiles object, however,
+    /// remains in the open state. You must call \c CloseFile() when finished using it. Other
+    /// methods, such as \c GetXMP(), can only be used between the \c OpenFile() and \c CloseFile()
+    /// calls. The \c XMPFiles destructor does not call \c CloseFile(); if you call it without closing,
+    /// any pending updates are lost.
     ///
-    /// The defined closeFlags bits are:
+    /// If the file is opened for update (passing \c #kXMPFiles_OpenForUpdate), the disk file remains
+    /// open until \c CloseFile() is called. The disk file is only updated once, when \c CloseFile()
+    /// is called, regardless of how many calls are made to \c PutXMP().
     ///
-    /// \li kXMPFiles_UpdateSafely - Write into a temporary file then swap for crash safety.
-    
-    void CloseFile ( XMP_OptionBits closeFlags = 0 );
-	
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Get basic information about an opened file.
+    /// @param closeFlags Option flags for optional closing actions. This bit-flag constant is
+    /// defined:
     ///
-    /// \param filePath If not null, returns the path passed to OpenFile.
+    ///   \li \c #kXMPFiles_UpdateSafely - Write into a temporary file then swap for crash safety.
+
+    void CloseFile ( XMP_OptionBits closeFlags = 0 );
+
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c GetFileInfo() retrieves basic information about an opened file.
     ///
-    /// \param openFlags If not null, returns the flags passed to OpenFile.
+    /// @param filePath [out] A buffer in which to return the path passed to \c OpenFile(). Can be
+    /// null if value is not wanted.
     ///
-    /// \param format If not null, returns the format of the file.
+    /// @param openFlags  [out] A buffer in which to return the option flags passed to
+    /// \c OpenFile(). Can be null if value is not wanted.
     ///
-    /// \param handlerFlags If not null, returns the handler's capability flags.
+    /// @param format [out] A buffer in which to return the file format. Can be null if value is not
+    /// wanted.
+    /// @param handlerFlags  [out] A buffer in which to return the handler's capability flags. Can
+    /// be null if value is not wanted.
     ///
-    /// \result Returns true if a file is opened, false otherwise. This notion of "open" really means
-    /// that OpenFile has been called but CloseFile has not. The actual disk file might be closed in
-    /// the host file system sense, as explained for OpenFile.
-	
+    /// @return True if the file object is in the open state; that is, \c OpenFile() has been called
+    /// but \c CloseFile() has not. False otherwise. Even if the file object is open, the actual
+    /// disk file might be closed in the host file-system sense; see \c OpenFile().
+
 	bool GetFileInfo ( tStringObj *     filePath = 0,
 					   XMP_OptionBits * openFlags = 0,
 					   XMP_FileFormat * format = 0,
     				   XMP_OptionBits * handlerFlags = 0 );
-	
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Set the callback function used to check for a user signaled abort.
+
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c SetAbortProc() registers a callback function used to check for a user-signaled abort.
     ///
-    /// \param abortProc The callback function used to check for a user signaled abort. It will be
-    /// called periodically to allow an abort of time consuming operations. The abort results in an
-    /// exception being thrown. The callback function should return true to signal an abort.
+    /// The specified procedure is called periodically to allow a user to cancel time-consuming
+    /// operations. The callback function should return true to signal an abort, which results in an
+    /// exception being thrown.
     ///
-    /// \param abortArg An argument passed to the callback function.
+    /// @param abortProc The callback function.
+    ///
+    /// @param abortArg A pointer to caller-defined data to pass to the callback function.
 
     void SetAbortProc ( XMP_AbortProc abortProc,
     					void *        abortArg );
 
     /// @}
-	
-	//  ============================================================================================
-    /// \name Metadata Access Functions
+
+	// =============================================================================================
+    /// \name Accessing metadata
     /// @{
-	
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Obtain the XMP.
-    ///
-    /// \c GetXMP is used to obtain the parsed XMP, and/or the raw XMP packet, and/or information
-    /// about the raw XMP packet. If all parameters are null it simply tells if XMP is present or
-    /// not. The options provided when the file was opened determine if reconciliation is done with
-    /// other forms of metadata.
-    ///
-    /// \param xmpObj If not null, returns the parsed XMP.
-    ///
-    /// \param xmpPacket If not null, returns the raw XMP packet as stored in the file. The encoding
-    /// of the packet is given in the packetInfo. The string will be empty if the low level file
-    /// handler does not provide the raw packet.
-    ///
-    /// \param packetInfo If not null, returns the location and form of the raw XMP in the file. The
-    /// charForm and writeable flag reflect the raw XMP in the file. The parsed XMP property values
-    /// are always UTF-8. The writeable flag is taken from the packet trailer, it is only relevant
-    /// for "format ignorant" writing.
-    ///
-    /// \note The packetInfo struct always reflects the state of the XMP in the file. The offset,
-    /// length, and character form will not change as a result of calling \c PutXMP unless the file
-    /// is also written.
     ///
-    /// \note Some file handlers might not return location or contents of the raw packet string.
-    /// Check the \c kXMPFiles_ReturnsRawPacket bit returned by GetFormatInfo if you depend on this.
-    /// If the low level file handler does not provide the raw packet location then the offset and
-    /// length will both be 0, the charForm will be UTF-8, and the writeable flag will be false.
-    ///
-    /// \result Returns true if the file has XMP, false otherwise.
-    
+    /// These functions allow you to retrieve XMP metadata from open files, so that you can use the
+    /// \c TXMPMeta API to manipulate it. The \c PutXMP() functions update the XMP packet in memory.
+    /// Changed XMP is not actually written out to the file until the file is closed.
+
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c GetXMP() retrieves the XMP metadata from an open file.
+    ///
+    /// The function reports whether XMP is present in the file; you can choose to retrieve any or
+    /// all of the parsed XMP, the raw XMP packet,or information about the raw XMP packet. The
+    /// options provided when the file was opened determine if reconciliation is done with other
+    /// forms of metadata.
+    ///
+    /// @param xmpObj [out] An XMP object in which to return the parsed XMP metadata. Can be null.
+    ///
+    /// @param xmpPacket [out] An string object in which to return the raw XMP packet as stored in
+    /// the file. Can be null. The encoding of the packet is given in the \c packetInfo. Returns an
+    /// empty string if the low level file handler does not provide the raw packet.
+    ///
+    /// @param packetInfo [out] An string object in which to return the location and form of the raw
+    /// XMP in the file. \c #XMP_PacketInfo::charForm and \c #XMP_PacketInfo::writeable reflect the
+    /// raw XMP in the file. The parsed XMP property values are always UTF-8. The writeable flag is
+    /// taken from the packet trailer; it applies only to "format ignorant" writing. The
+    /// \c #XMP_PacketInfo structure always reflects the state of the XMP in the file. The offset,
+    /// length, and character form do not change as a result of calling \c PutXMP() unless the file
+    /// is also written. Some file handlers might not return location or contents of the raw packet
+    /// string. To determine whether one does, check the \c #kXMPFiles_ReturnsRawPacket bit returned
+    /// by \c GetFormatInfo(). If the low-level file handler does not provide the raw packet
+    /// location, \c #XMP_PacketInfo::offset and \c #XMP_PacketInfo::length are both 0,
+    /// \c #XMP_PacketInfo::charForm is UTF-8, and \c #XMP_PacketInfo::writeable is false.
+    ///
+    /// @return True if the file has XMP, false otherwise.
+
     bool GetXMP ( SXMPMeta *       xmpObj = 0,
     			  tStringObj *     xmpPacket = 0,
     			  XMP_PacketInfo * packetInfo = 0 );
-	
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Obtain the native thumbnail.
-    ///
-    /// \c GetThumbnail is used to obtain native thumbnail information, if the associated file
-    /// handler supports that and the thumbnail was cached by OpenFile. This requires that
-    /// kXMPFiles_OpenCacheTNail be passed to OpenFile. The tnailInfo output pointer can be null,
-    /// in which case GetThumbnail will simply tell if a recognized native thumbnail is present.
-    ///
-    /// \param tnailInfo If not null, returns information about a recognized native thumbnail, and
-    /// some related information about the primary image if appropriate.
-    ///
-    /// \note The returned thumbnail information can be incomplete. What gets returned can depend on
-    /// the file format, the file handler's capabilities, and the specific file content.
-    ///
-    /// \li The fullHeight, fullWIdth, and fullOrientation fields are only meaningful for image files.
-    /// They are not meaningful for multi-page files such as PDF or InDesign, for dynamic audio or
-    /// video files, etc. The fields will be zero if not meaningful or not determined.
-    ///
-    /// \li The tnailImage and tnailSize fields might be zero even if a "recognized" thumbnail is
-    /// present. Being recognized means only that the handler has determined that the file does
-    /// contain a native thumbnail. The thumbnail data might be of a format that the file handler
-    /// cannot (or does not) return a single contiguous block of thumbnail data. A possible case of
-    /// this is a TIFF uncompressed thumbnail, the handler might not have logic to gather the various
-    /// disjoint pieces of the thumbnail from the overall TIFF stream.
-    ///
-    /// \result Returns true if a recognized native thumbnail is presentand the thumbnail was
-    /// cached by OpenFile. This requires that kXMPFiles_OpenCacheTNail be passed to OpenFile. Note
-    /// that GetThumbnail can return true but still not return an actual thumbnail image, see the
-    /// above note.
-    
+
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c GetThumbnail() retrieves the native thumbnail from an open file.
+    ///
+    /// Use this function to obtain native thumbnail information, if the associated file handler
+    /// supports that and the thumbnail was cached by the call to \c OpenFile(); that is, the
+    /// \c #kXMPFiles_OpenCacheTNail option flag was set. The return value reports whether a thumbnail
+    /// is present in the file.
+    ///
+	/// The returned thumbnail information can be incomplete, depending on the file format, the file
+	/// handler's capabilities, and the specific file content.
+    ///
+    ///   \li The \c #XMP_ThumbnailInfo::fullWidth, \c fullHeight, and \c fullOrientation fields are
+    ///   only meaningful for image files. They are not meaningful for multi-page files such as PDF
+    ///   or InDesign, for dynamic audio or video files, and so on. The field values are zero if not
+    ///   meaningful or not determined.
+    ///   \li The \c #XMP_ThumbnailInfo::tnailImage and \c #XMP_ThumbnailInfo::tnailSize fields
+    ///   might be zero even if a recognized thumbnail is	present.
+    ///
+    /// Being recognized means only that the handler has determined that the file does contain a
+    /// native thumbnail. The thumbnail data might be of a format that the file handler cannot
+    /// return as a single contiguous block of thumbnail data. For example, for a TIFF uncompressed
+    /// thumbnail, the handler might not have logic to gather the various disjoint pieces of the
+    /// thumbnail from the overall TIFF stream.
+    ///
+    /// @param tnailInfo [out] Optional. A buffer in which to return information about a recognized
+    /// native thumbnail, and related information about the primary image if appropriate. Can be
+    /// null if the information is not desired.
+    ///
+    /// @return True if a recognized native thumbnail is present and the thumbnail was cached by the
+    /// call to \c OpenFile(); that is, the \c #kXMPFiles_OpenCacheTNail option flag was set. Can
+    /// return true even if the function cannot retrieve the actual thumbnail image.
+
     bool GetThumbnail ( XMP_ThumbnailInfo * tnailInfo );
-	
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Update the XMP.
-    ///
-    /// \c PutXMP supplies new XMP for the file. However, the file is not actully written until
-    /// closed. The options provided when the file was opened determine if reconciliation is done
-    /// with other forms of metadata. Overloads are provided to pass the XMP as an XMP
-    /// object, a string object, or a "const char *" plus length.
-    
+
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c PutXMP() updates the XMP metadata in this object without writing out the file.
+    ///
+    /// This function supplies new XMP for the file. However, the disk file is not written until the
+    /// object is closed with \c CloseFile(). The options provided when the file was opened
+    /// determine if reconciliation is done with other forms of metadata.
+    ///
+    /// @param xmpObj The new metadata as an XMP object.
+
     void PutXMP ( const SXMPMeta & xmpObj );
 
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c PutXMP() updates the XMP metadata in this object without writing out the file,
+	/// using a string object for input.
+    ///
+    /// Overloads the basic form of the function, allowing you to pass the metadata as a string object
+	/// instead of an XMP object. It is otherwise identical; see details in the canonical form.
+	///
+    /// @param xmpPacket The new metadata as a string object containing a complete XMP packet.
+
     void PutXMP ( const tStringObj & xmpPacket );
-    
+
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c PutXMP() updates the XMP metadata in this object without writing out the file,
+   	/// using a string object and optional length.
+    ///
+    /// Overloads the basic form of the function, allowing you to pass the metadata as a string object
+	/// instead of an XMP object. It is otherwise identical; see details in the canonical form.
+    ///
+    /// @param xmpPacket The new metadata as a <tt>const char *</tt> string containing an XMP packet.
+    ///
+    /// @param xmpLength Optional. The number of bytes in the string. If not supplied, the string is
+    /// assumed to be nul-terminated.
+
     void PutXMP ( XMP_StringPtr xmpPacket,
                   XMP_StringLen xmpLength = kXMP_UseNullTermination );
-	
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Determine if the XMP can be updated.
-    ///
-    /// \c CanPutXMP determines if the XMP can (probably) be updated. The provided XMP is only used
-    /// to obtain the length of the serialized packet. The new XMP is not kept, calling this will
-    /// not cause the file to be written when closed. Overloads are provided to pass the XMP as an
-    /// XMP object, a string object, or a "const char *" plus length. This is implemented roughly
-    /// as:
-    ///
-    /// \code
-    ///  bool CanPutXMP ( XMP_StringPtr xmpPacket )
-    ///  {
-    /// 	XMP_FileFormat format;
-	/// 	this->GetFileInfo ( 0, &format, 0 );
-	///
-	/// 	XMP_OptionBits formatFlags;
-	/// 	GetFormatInfo ( format, &formatFlags );
-    /// 
-    /// 	if ( (formatFlags & kXMPFiles_CanInjectXMP) && (formatFlags & kXMPFiles_CanExpand) ) return true;
-    ///
-    /// 	XMP_PacketInfo packetInfo;
-    /// 	bool hasXMP = this->GetXMP ( 0, 0, &packetInfo );
-    ///
-    /// 	if ( ! hasXMP ) {
-    /// 		if ( formatFlags & kXMPFiles_CanInjectXMP ) return true;
-    /// 	} else {
-    /// 		if ( (formatFlags & kXMPFiles_CanExpand) ||
-    /// 			 (packetInfo.length >= strlen(xmpPacket)) ) return true;
-    /// 	}
-    /// 
-    /// 	return false;
-    /// 
-    ///  }
-    /// \endcode
-    
+
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c CanPutXMP() reports whether this file can be updated with a specific XMP packet.
+    ///
+    /// Use to determine if the file can probably be updated with a given set of XMP metadata. This
+    /// depends on the size of the packet, the options with which the file was opened, and the
+    /// capabilities of the handler for the file format. The function obtains the length of the
+    /// serialized packet for the provided XMP, but does not keep it or modify it, and does not
+    /// cause the file to be written when closed. This is implemented roughly as follows:
+    ///
+    /// <pre>
+    /// bool CanPutXMP ( XMP_StringPtr xmpPacket )
+    /// {
+    ///    XMP_FileFormat format;
+    ///    this->GetFileInfo ( 0, &format, 0 );
+    ///
+    ///    XMP_OptionBits formatFlags;
+    ///    GetFormatInfo ( format, &formatFlags );
+    ///
+    ///    if ( (formatFlags & kXMPFiles_CanInjectXMP) && (formatFlags & kXMPFiles_CanExpand) ) return true;
+    ///
+    ///    XMP_PacketInfo packetInfo;
+    ///    bool hasXMP = this->GetXMP ( 0, 0, &packetInfo );
+    ///
+    ///    if ( ! hasXMP ) {
+    ///       if ( formatFlags & kXMPFiles_CanInjectXMP ) return true;
+    ///    } else {
+    ///       if ( (formatFlags & kXMPFiles_CanExpand) ||
+    ///            (packetInfo.length >= strlen(xmpPacket)) ) return true;
+    ///    }
+    ///    return false;
+    /// }
+    /// </pre>
+    ///
+    /// @param xmpObj The proposed new metadata as an XMP object.
+
     bool CanPutXMP ( const SXMPMeta & xmpObj );
 
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c CanPutXMP() reports whether this file can be updated with a specific XMP packet,
+    /// passed in a string object.
+    ///
+    /// Overloads the basic form of the function, allowing you to pass the metadata as a string object
+	/// instead of an XMP object. It is otherwise identical; see details in the canonical form.
+    ///
+    /// @param xmpPacket The proposed new metadata as a string object containing an XMP packet.
+
     bool CanPutXMP ( const tStringObj & xmpPacket );
-    
+
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c CanPutXMP() reports whether this file can be updated with a specific XMP packet,
+    /// passed in a string object.
+    ///
+    /// Overloads the basic form of the function, allowing you to pass the metadata as a string object
+	/// instead of an XMP object. It is otherwise identical; see details in the canonical form.
+    ///
+    /// @param xmpPacket The proposed new metadata as a <tt>const char *</tt> string containing an XMP packet.
+    ///
+    /// @param xmpLength Optional. The number of bytes in the string. If not supplied, the string
+    /// is assumed to be nul-terminated.
+
     bool CanPutXMP ( XMP_StringPtr xmpPacket,
                      XMP_StringLen xmpLength = kXMP_UseNullTermination );
 
diff --git a/public/include/TXMPIterator.hpp b/public/include/TXMPIterator.hpp
index 26bb141..c347cf0 100644
--- a/public/include/TXMPIterator.hpp
+++ b/public/include/TXMPIterator.hpp
@@ -14,183 +14,213 @@
 // of the Adobe license agreement accompanying it.
 // =================================================================================================
 
-//  ================================================================================================
+// =================================================================================================
 /// \file TXMPIterator.hpp
-/// \brief Template class for the XMP Toolkit iteration services.
+/// \brief API for access to the XMP Toolkit iteration services.
 ///
-/// This template class provides iteration services for the XMP Toolkit. It should be instantiated
-/// with a string class such as <tt>std::string</tt>. Please read the general usage notes for
-/// information on the overall architecture of the XMP API.
-//  ================================================================================================
+/// \c TXMPIterator is the template class providing iteration services for the XMP Toolkit. It must
+/// be instantiated with a string class such as \c std::string. See the instructions in XMP.hpp, and
+/// the Overview for a discussion of the overall architecture of the XMP API.
+// =================================================================================================
 
-//  ================================================================================================
+// =================================================================================================
 /// \class TXMPIterator TXMPIterator.hpp
-/// \brief Template class for the XMP Toolkit iteration services.
+/// @brief API for access to the XMP Toolkit iteration services.
 ///
-/// This template class provides iteration services for the XMP Toolkit. It should be instantiated
-/// with a string class such as <tt>std::string</tt>. Please read the general usage notes for
-/// information on the overall architecture of the XMP API.
+/// \c TXMPIterator provides a uniform means to iterate over the schema and properties within an XMP
+/// object. \c TXMPIterator is a template class which must be instantiated with a string class such
+/// as \c std::string. See the instructions in XMP.hpp, and the Overview for a discussion of the
+/// overall architecture of the XMP API. Access these functions through the concrete class,
+/// \c SXMPIterator.
 ///
-/// \c TXMPIterator provides a uniform means to iterate over several XMP data structures, including
-/// the schema and properties within an XMP object plus global tables such as registered
-/// namespaces. The template wraps a string class around the raw XMP API, so that output strings
-/// are automatically copied and access is fully thread safe.  String objects are only necessary
-/// for output strings. Input string are literals and passed as typical C <tt>const char *</tt>.
+/// @note Only XMP object iteration is currently available. Future development may include iteration
+/// over global tables, such as registered namespaces.
 ///
-/// The template parameter, class \c TtStringObj, is described in the XMP.hpp umbrella header.
+/// To understand how iteration works, you should have a thorough understanding of the XMP data
+/// tree, as described in the XMP Specification Part 1. You might also find it helpful to create
+/// some complex XMP and examine the output of \c TXMPMeta::DumpObject().
 ///
-/// \note Only XMP object iteration is implemented at this time. There are no table iterators yet.
+///   \li The top of the XMP data tree is a single root node. This does not explicitly appear in the
+///   dump and is never visited by an iterator; that is, it is never returned from
+///   \c TXMPIterator::Next().
 ///
-/// Iteration over the schema and properties within an XMP object is the most important and complex
-/// use of \c TTXMPIterator. It is helpful to have a thorough understanding of the XMP data tree.
-/// One way to learn this is to create some complex XMP and examine the output of
-/// <tt>TXMPMeta::DumpObject</tt>. This is also described in the XMP Specification, in the XMP Data
-/// Model chapter.
+///   \li Beneath the root are schema nodes; these collect the top-level properties in the same
+///   namespace. They are created and destroyed implicitly.
 ///
-/// The top of the XMP data tree is a single root node. This does not explicitly appear in the dump
-/// and is never visited by an iterator (that is, it is never returned from
-/// <tt>TXMPIterator::Next</tt>). Beneath the root are schema nodes. These are just collectors for
-/// top level properties in the same namespace. They are created and destroyed implicitly. Beneath
-/// the schema nodes are the property nodes. The nodes below a property node depend on its type
-/// (simple, struct, or array) and whether it has qualifiers.
+///   \li Beneath the schema nodes are the property nodes. The nodes below a property node depend on
+///   its type (simple, struct, or array) and whether it has qualifiers.
 ///
-/// A \c TXMPIterator constructor defines a starting point for the iteration and options that control
-/// how it proceeds. By default the iteration starts at the root and visits all nodes beneath it in
-/// a depth first manner. The root node is not visited, the first visited node is a schema node. You
-/// can provide a schema name or property path to select a different starting node. By default this
-/// visits the named root node first then all nodes beneath it in a depth first manner.
+/// A \c TXMPIterator constructor defines a starting point for the iteration, and options that
+/// control how it proceeds. By default, iteration starts at the root and visits all nodes beneath
+/// it in a depth-first manner. The root node iteself is not visited; the first visited node is a
+/// schema node. You can provide a schema name or property path to select a different starting node.
+/// By default, this visits the named root node first then all nodes beneath it in a depth-first
+/// manner.
 ///
-/// The <tt>TXMPIterator::Next</tt> method delivers the schema URI, path, and option flags for the
-/// node being visited. If the node is simple it also delivers the value. Qualifiers for this node
+/// The function \c TXMPIterator::Next() delivers the schema URI, path, and option flags for the
+/// node being visited. If the node is simple, it also delivers the value. Qualifiers for this node
 /// are visited next. The fields of a struct or items of an array are visited after the qualifiers
 /// of the parent.
 ///
-/// The options to control the iteration are:
-///
-/// \li \c kXMP_IterJustChildren - Visit just the immediate children of the root. Skip the root
-/// itself and all nodes below the immediate children. This omits the qualifiers of the immediate
-/// children, the qualifier nodes being below what they qualify.
-///
-/// \li \c kXMP_IterJustLeafNodes - Visit just the leaf property nodes and their qualifiers.
-///
-/// \li \c kXMP_IterJustLeafName - Return just the leaf component of the node names. The default is
-/// to return the full path name.
-///
-/// \li \c kXMP_IterIncludeAliases - Include aliases as part of the iteration. Since aliases are not
-/// actual nodes the default iteration does not visit them.
-///
-/// \li \c kXMP_IterOmitQualifiers - Do not visit the qualifiers of a node.
-///
-//  ================================================================================================
+/// You can specify options when contructing the iteration object to control how the iteration is
+/// performed.
+///
+///   \li \c #kXMP_IterJustChildren - Visit just the immediate children of the root. Skip the root
+///   itself and all nodes below the immediate children. This omits the qualifiers of the immediate
+///   children, the qualifier nodes being below what they qualify.
+///   \li \c #kXMP_IterJustLeafNodes - Visit just the leaf property nodes and their qualifiers.
+///   \li \c #kXMP_IterJustLeafName - Return just the leaf component of the node names. The default
+///   is to return the full path name.
+///   \li \c #kXMP_IterIncludeAliases - Include aliases as part of the iteration. Since aliases are
+///   not actual nodes the default iteration does not visit them.
+///   \li \c #kXMP_IterOmitQualifiers - Do not visit the qualifiers of a node.
+// =================================================================================================
 
 #include "client-glue/WXMPIterator.hpp"
 
-template <class tStringObj>
-class TXMPIterator {
+template <class tStringObj> class TXMPIterator {
 
 public:
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Assignment operator, assigns the internal ref and increments the ref count.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief Assignment operator, assigns the internal ref and increments the ref count.
+    ///
+    /// Assigns the internal reference from an existing object and increments the reference count on
+    /// the underlying internal XMP iterator.
     ///
-    /// The assignment operator assigns the internal ref from the rhs object and increments the
-    /// reference count on the underlying internal XMP iterator.
+    /// @param rhs An existing iteration object.
 
     void operator= ( const TXMPIterator<tStringObj> & rhs );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Copy constructor, creates a client object refering to the same internal object.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief Copy constructor, creates a client object refering to the same internal object.
     ///
-    /// The copy constructor creates a new client iterator that refers to the same underlying iterator.
+    /// Creates a new client iterator that refers to the same underlying iterator as an existing object.
+    ///
+    /// @param original An existing iteration object to copy.
 
     TXMPIterator ( const TXMPIterator<tStringObj> & original );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Construct an iterator for the properties within an XMP object.
-    ///
-    /// Construct an iterator for the properties within an XMP object. The general operation of an
-    /// XMP object iterator was described above. Overloaded forms are provided to iterate the entire
-    /// data tree, properties within a specific schema, or a subtree rooted at a specific node.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief Constructs an iterator for properties within a schema in an XMP object.
     ///
-    /// \param xmpObj The XMP object over which to iterate.
+    /// See the class description for the general operation of an  XMP object iterator.
+    /// Overloaded forms are provided to iterate the entire data tree,
+    /// a subtree rooted at a specific node, or properties within a specific schema.
     ///
-    /// \param schemaNS Optional schema namespace URI to restrict the iteration. Omitted (visit all
-    /// schema) by passing 0 or "".
+    /// @param xmpObj The XMP object over which to iterate.
     ///
-    /// \param propName Optional property name to restrict the iteration. May be an arbitrary path
-    /// expression. Omitted (visit all properties) by passing 0 or "". If not null/empty a schema
-    /// URI must also be provided.
+    /// @param schemaNS Optional schema namespace URI to restrict the iteration. To visit all of the
+    /// schema, pass 0 or the empty string "".
     ///
-    /// \param options Option flags to control the iteration.
+    /// @param propName Optional property name to restrict the iteration. May be an arbitrary path
+    /// expression. If provided, a schema URI must also be provided. To visit all properties, pass 0
+    /// or the empty string "".
     ///
-    /// The available option flags are:
+    /// @param options Option flags to control the iteration. A logical OR of these bit flag constants:
+    ///   \li \c #kXMP_IterJustChildren - Visit only the immediate children of the root; default visits subtrees.
+    ///   \li \c #kXMP_IterJustLeafNodes - Visit only the leaf nodes; default visits all nodes.
+    ///   \li \c #kXMP_IterJustLeafName - Return just the leaf part of the path; default returns the full path.
+    ///   \li \c #kXMP_IterOmitQualifiers - Omit all qualifiers.
     ///
-    /// \li \c kXMP_IterJustChildren - Just visit the immediate children of the root, default is subtree.
-    /// \li \c kXMP_IterJustLeafNodes - Just visit the leaf nodes, default visits all nodes.
-    /// \li \c kXMP_IterJustLeafName - Return just the leaf part of the path, default is the full path.
-    /// \li \c kXMP_IterOmitQualifiers - Omit all qualifiers.
+    /// @return The new TXMPIterator object.
 
     TXMPIterator ( const TXMPMeta<tStringObj> & xmpObj,
                    XMP_StringPtr  schemaNS,
                    XMP_StringPtr  propName,
                    XMP_OptionBits options = 0 );
 
+    // ---------------------------------------------------------------------------------------------
+    /// @brief Constructs an iterator for a subtree of properties within an XMP object.
+    ///
+    /// See the class description for the general operation of an  XMP object iterator. Overloaded
+    /// forms are provided to iterate the entire data tree, a subtree rooted at a specific node, or
+    /// properties within a specific schema.
+    ///
+    /// @param xmpObj The XMP object over which to iterate.
+    ///
+    /// @param schemaNS Optional schema namespace URI to restrict the iteration. To visit all of the
+    /// schema, pass 0 or the empty string "".
+    ///
+    /// @param options Option flags to control the iteration. A logical OR of these bit flag constants:
+    ///   \li \c #kXMP_IterJustChildren - Visit only the immediate children of the root; default visits subtrees.
+    ///   \li \c #kXMP_IterJustLeafNodes - Visit only the leaf nodes; default visits all nodes.
+    ///   \li \c #kXMP_IterJustLeafName - Return just the leaf part of the path; default returns the full path.
+    ///   \li \c #kXMP_IterOmitQualifiers - Omit all qualifiers.
+    ///
+    /// @return The new TXMPIterator object.
+
     TXMPIterator ( const TXMPMeta<tStringObj> & xmpObj,
                    XMP_StringPtr  schemaNS,
                    XMP_OptionBits options = 0 );
 
+    // ---------------------------------------------------------------------------------------------
+    /// @brief Constructs an iterator for the entire data tree within an XMP object.
+    ///
+    /// See the class description for the general operation of an  XMP object iterator. Overloaded
+    /// forms are provided to iterate the entire data tree, a subtree rooted at a specific node, or
+    /// properties within a specific schema.
+    ///
+    /// @param xmpObj The XMP object over which to iterate.
+    ///
+    /// @param options Option flags to control the iteration. A logical OR of these bit flag constants:
+    ///   \li \c #kXMP_IterJustChildren - Visit only the immediate children of the root; default visits subtrees.
+    ///   \li \c #kXMP_IterJustLeafNodes - Visit only the leaf nodes; default visits all nodes.
+    ///   \li \c #kXMP_IterJustLeafName - Return just the leaf part of the path; default returns the full path.
+    ///   \li \c #kXMP_IterOmitQualifiers - Omit all qualifiers.
+    ///
+    /// @return The new \c TXMPIterator object.
+
     TXMPIterator ( const TXMPMeta<tStringObj> & xmpObj,
                    XMP_OptionBits options = 0 );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Construct an iterator for the global tables of the XMP toolkit.
-    ///
-    /// \note <b>Not yet implemented.</b> File a bug if you need this.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief Constructs an iterator for the global tables of the XMP toolkit.	Not implemented.
 
     TXMPIterator ( XMP_StringPtr  schemaNS,
                    XMP_StringPtr  propName,
                    XMP_OptionBits options );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Destructor, typical virtual destructor.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief Destructor, typical virtual destructor.
 
     virtual ~TXMPIterator() throw();
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Visit the next node in the iteration.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c Next() visits the next node in the iteration.
     ///
-    /// \result Returns true if there was another node to visit, false if the iteration is done.
+    /// Proceeds to the next node according to the options specified on creation of this object, and
+    /// delivers the schema URI, path, and option flags for the node being visited. If the node is
+    /// simple, it also delivers the value.
     ///
-    /// \param schemaNS A pointer to the string that is assigned the schema namespace URI of
-    /// the current property. May be null if the value is not wanted.
+    /// @param schemaNS [out] A string object in which to return the assigned the schema namespace
+    /// URI of the current property. Can be null if the value is not wanted.
     ///
-    /// \param propPath A pointer to the string that is assigned the XPath name of the current
-    /// property. May be null if the value is not wanted.
+    /// @param propPath [out]  A string object in which to return the XPath name of the current
+    /// property. Can be null if the value is not wanted.
     ///
-    /// \param propValue A pointer to the string that is assigned the value of the current
-    /// property. May be null if the value is not wanted.
+    /// @param propValue  [out] A string object in which to return the value of the current
+    /// property. Can be null if the value is not wanted.
     ///
-    /// \param options A pointer to the XMP_OptionBits variable that is assigned the flags
-    /// describing the current property.
+    /// @param options  [out] A buffer in which to return the flags describing the current property,
+    /// which are a logical OR of \c #XMP_OptionBits bit-flag constants.
+    ///
+    /// @return True if there was another node to visit, false if the iteration is complete.
 
-    bool
-    Next ( tStringObj *     schemaNS = 0,
-           tStringObj *     propPath = 0,
-           tStringObj *     propValue = 0,
-           XMP_OptionBits * options = 0 );
+    bool Next ( tStringObj *     schemaNS = 0,
+          		tStringObj *     propPath = 0,
+           		tStringObj *     propValue = 0,
+           		XMP_OptionBits * options = 0 );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Skip some portion of the remaining iterations.
-    ///
-    /// \param options Option flags to control the iteration.
-    ///
-    /// The available option flags are:
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c Skip() skips some portion of the remaining iterations.
     ///
-    /// \li \c kXMP_IterSkipSubtree -  Skip the subtree below the current node.
-    /// \li \c kXMP_IterSkipSiblings - Skip the subtree below and remaining siblings of the current node.
+    /// @param options Option flags to control the iteration, a logical OR of these bit-flag
+    /// constants:
+    ///   \li \c #kXMP_IterSkipSubtree -  Skip the subtree below the current node.
+    ///   \li \c #kXMP_IterSkipSiblings - Skip the subtree below and remaining siblings of the current node.
 
-    void
-    Skip ( XMP_OptionBits options );
+    void Skip ( XMP_OptionBits options );
 
 private:
 
diff --git a/public/include/TXMPMeta.hpp b/public/include/TXMPMeta.hpp
index ef1a5fc..209548c 100644
--- a/public/include/TXMPMeta.hpp
+++ b/public/include/TXMPMeta.hpp
@@ -7,68 +7,46 @@
 
 // =================================================================================================
 // ADOBE SYSTEMS INCORPORATED
-// Copyright 2002-2007 Adobe Systems Incorporated
+// Copyright 2002-2008 Adobe Systems Incorporated
 // All Rights Reserved
 //
 // NOTICE:  Adobe permits you to use, modify, and distribute this file in accordance with the terms
 // of the Adobe license agreement accompanying it.
 // =================================================================================================
 
-//  ================================================================================================
+// =================================================================================================
 /// \file TXMPMeta.hpp
-/// \brief Template class for the XMP Toolkit core services.
+/// \brief API for access to the XMP Toolkit core services.
+///
+/// \c TXMPMeta is the template class providing the core services of the XMP Toolkit. It must be
+/// instantiated with a string class such as \c std::string. Read the Toolkit Overview for
+/// information about the overall architecture of the XMP API, and the documentation for \c XMP.hpp
+/// for specific instantiation instructions.
 ///
-/// TXMPMeta is the template class providing the core services of the XMP Toolkit. It should be
-/// instantiated with a string class such as <tt>std::string</tt>. Please read the general toolkit
-/// usage notes for information about the overall architecture of the XMP API.
-//  ================================================================================================
+/// Access these functions through the concrete class, \c SXMPMeta.
+// =================================================================================================
 
-//  ================================================================================================
+// =================================================================================================
 /// \class TXMPMeta TXMPMeta.hpp
-/// \brief Template class for the XMP Toolkit core services.
+/// \brief API for access to the XMP Toolkit core services.
 ///
 /// \c TXMPMeta is the template class providing the core services of the XMP Toolkit. It should be
-/// instantiated with a string class such as std::string. Please read the general toolkit usage notes
-/// for information about the overall architecture of the XMP API.
-///
-/// This template wraps a string object class around the raw XMP API. This provides two significant
-/// benefits, output strings are automatically copied and access is fully thread safe. The
-/// umbrella header, \c XMP.hpp, provides an \c SXMPMeta typedef for the instantiated template. String
-/// objects are only necessary for output strings. Input string are literals and passed as typical
-/// C <tt>const char *</tt>.
-///
-/// The template parameter, class \c TtStringObj, is described in the XMP.hpp umbrella header.
-///
-/// <b>Be aware that the \c TXMPMeta class is a normal C++ template, it is instantiated and local to
-/// each client executable. As are the other TXMP* classes. Different clients might not even use the
-/// same string type to instantiate \c TXMPMeta.</b>
-///
-/// Because of this you should not pass \c SXMPMeta objects, or pointers to \c SXMPMeta objects,
-/// across DLL boundaries. There is a safe internal reference that you can pass, then construct a
-/// local object on the callee side. This construction does not create a cloned XMP tree, it is the
-/// same underlying XMP object safely wrapped in each client's \c SXMPMeta object.
+/// instantiated with a string class such as \c std::string. Read the Toolkit Overview for
+/// information about the overall architecture of the XMP API, and the documentation for \c XMP.hpp
+/// for specific instantiation instructions.
 ///
-/// Use GetInternalRef and the associated constructor like this:
-/// \code
-///  --- The callee's header contains:
-///  CalleeMethod ( XMPMetaRef xmpRef );
+/// Access these functions through the concrete class, \c SXMPMeta.
 ///
-///  --- The caller's code contains:
-///  SXMPMeta callerXMP;
-///  CalleeMethod ( callerXMP.GetInternalRef() );
-///
-///  --- The callee's code contains:
-///  SXMPMeta calleeXMP ( xmpRef );
-/// \endcode
-//  ================================================================================================
+/// You can create \c TXMPMeta objects (also called XMP objects) from metadata that you construct,
+/// or that you obtain from files using the XMP Toolkit's XMPFiles component; see \c TXMPFiles.hpp.
+// =================================================================================================
 
 template <class tStringObj> class TXMPIterator;
 template <class tStringObj> class TXMPUtils;
 
 // -------------------------------------------------------------------------------------------------
 
-template <class tStringObj>
-class TXMPMeta {
+template <class tStringObj> class TXMPMeta {
 
 public:
 
@@ -76,29 +54,46 @@ public:
     // Initialization and termination
     // ==============================
 
-    //  --------------------------------------------------------------------------------------------
+    // ---------------------------------------------------------------------------------------------
     /// \name Initialization and termination
+    ///
     /// @{
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Obtain version information.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c GetVersionInfo() retrieves runtime version information.
+    ///
+    /// The header \c XMPVersion.hpp defines a static version number for the XMP Toolkit, which
+    /// describes the version of the API used at client compile time. It is not necessarily the same
+    /// as the runtime version. Do not base runtime decisions on the static version alone; you can,
+    /// however, compare the runtime and static versions.
+    ///
+    /// This function is static; make the call directly from the concrete class (\c SXMPMeta). The
+    /// function can be called before calling \c TXMPMeta::Initialize().
+    ///
+    /// @param info [out] A buffer in which to return the version information.
 
-    static void
-    GetVersionInfo ( XMP_VersionInfo * info );
+    static void GetVersionInfo ( XMP_VersionInfo * info );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Initialize the XMP Toolkit.
-    ///
-    /// The XMP Toolkit may be explicitly initialized before use. The allocate/delete parameters must
-    /// be either both null (0), or both non-null.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c Initialize() explicitly initializes the XMP Toolkit before use. */
 
-    static bool
-    Initialize();
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Terminate the XMP Toolkit.
+    /// Initializes the XMP Toolkit.
+    ///
+    /// Call this function before making any other calls to the \c TXMPMeta functions, except
+    /// \c TXMPMeta::GetVersionInfo().
+    ///
+    /// This function is static; make the call directly from the concrete class (\c SXMPMeta).
+    ///
+    /// @return True on success. */
+    static bool Initialize();
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c Terminate() explicitly terminates usage of the XMP Toolkit.
+    ///
+    /// Frees structures created on initialization.
+    ///
+    /// This function is static; make the call directly from the concrete class (\c SXMPMeta).
 
-    static void
-    Terminate();
+    static void Terminate();
 
     /// @}
 
@@ -106,61 +101,74 @@ public:
     // Constuctors and destructor
     // =========================
 
-    //  --------------------------------------------------------------------------------------------
+    // ---------------------------------------------------------------------------------------------
     /// \name Constructors and destructor
     /// @{
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Default constructor, creates an empty object.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief Default constructor, creates an empty object.
     ///
     /// The default constructor creates a new empty \c TXMPMeta object.
-
+    ///
+    /// @return The new object. */
     TXMPMeta();
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Copy constructor, creates a client object refering to the same internal object.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief Copy constructor, creates a client object refering to the same internal object.
+    ///
+    /// The copy constructor creates a new \c TXMPMeta object that refers to the same internal XMP
+    /// object. as an existing \c TXMPMeta object.
     ///
-    /// The copy constructor creates a new \c TXMPMeta object that refers to the same internal XMP object.
+    /// @param original The object to copy.
+    ///
+    /// @return The new object. */
 
     TXMPMeta ( const TXMPMeta<tStringObj> & original );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Assignment operator, assigns the internal ref and increments the ref count.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief Assignment operator, assigns the internal reference and increments the reference count.
     ///
     /// The assignment operator assigns the internal ref from the rhs object and increments the
     /// reference count on the underlying internal XMP object.
 
     void operator= ( const TXMPMeta<tStringObj> & rhs );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Reconstruct an XMP object from an internal ref.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief Reconstructs an XMP object from an internal reference.
+    ///
+    /// This constructor creates a new \c TXMPMeta object that refers to the underlying reference object
+    /// of an existing \c TXMPMeta object. Use to safely pass XMP objects across DLL boundaries.
     ///
-    /// This constructor creates a new \c TXMPMeta object that refers to the underlying \c xmpRef,
-    /// which was obtained from some other XMP object by the \c GetInternalRef method. This is used
-    /// to safely pass XMP objects across DLL boundaries.
+    /// @param xmpRef The underlying reference object, obtained from some other XMP object with
+    /// \c TXMPMeta::GetInternalRef().
+    ///
+    /// @return The new object.
 
     TXMPMeta ( XMPMetaRef xmpRef );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Construct an object and parse one buffer of RDF into it.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief Constructs an object and parse one buffer of RDF into it.
     ///
     /// This constructor creates a new \c TXMPMeta object and populates it with metadata from a
-    /// buffer containing serialized RDF. This buffer must be a complete RDF parse stream. Pass
-    /// (0,0) to construct an empty \c TXMPMeta object. The result of an actual parse is identical
-    /// to creating an empty object then calling <tt>TXMPMeta::ParseFromBuffer</tt>. The RDF must be
-    /// complete. If you need to parse with multiple buffers, create an empty object and use
-    /// \c TXMPMeta::ParseFromBuffer.
+    /// buffer containing serialized RDF. This buffer must be a complete RDF parse stream.
+    ///
+    /// The result of passing serialized data to this function is identical to creating an empty
+    /// object then calling \c TXMPMeta::ParseFromBuffer(). To use the constructor, however, the RDF
+    /// must be complete. If you need to parse data from multiple buffers, create an empty object
+    /// and use  \c TXMPMeta::ParseFromBuffer().
     ///
-    /// \param buffer   A pointer to the buffer of RDF to be parsed. May be null if the length is 0.
+    /// @param buffer  A pointer to the buffer of RDF to be parsed. Can be null if the length is 0;
+    /// in this case, the function creates an empty object.
     ///
-    /// \param xmpSize  The length in bytes of the buffer.
+    /// @param xmpSize  The length in bytes of the buffer.
+    ///
+    /// @return The new object.
 
     TXMPMeta ( XMP_StringPtr buffer,
                XMP_StringLen xmpSize );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Destructor, typical virtual destructor.
-
+    // ---------------------------------------------------------------------------------------------
+    /// @brief Destructor, typical virtual destructor. */
     virtual ~TXMPMeta() throw();
 
     /// @}
@@ -169,51 +177,87 @@ public:
     // Global state functions
     // ======================
 
-    //  --------------------------------------------------------------------------------------------
+    // ---------------------------------------------------------------------------------------------
     /// \name Global option flags
     /// @{
-    /// The global option flags affect the overall behavior of the XMP Toolkit. The available options
-    /// are declared in <tt>XMP_Const.h</tt>. <b>(There are none at present.)</b>
+    /// Global option flags affect the overall behavior of the XMP Toolkit. The available options
+    /// will be declared in \c XMP_Const.h. There are none in this version of the Toolkit.
 
-    /// \brief GetGlobalOptions returns the set of global option flags.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c GetGlobalOptions() retrieves the set of global option flags. There are none in
+    /// this version of the Toolkit.
+    ///
+    /// This function is static; you can make the call from the class without instantiating it.
+    ///
+    /// @return A logical OR of global option bit-flag constants.
 
-    static XMP_OptionBits
-    GetGlobalOptions();
+     static XMP_OptionBits GetGlobalOptions();
 
-    /// \brief \c SetGlobalOptions updates the set of global option flags. The entire set is
-    /// replaced with the new values. If only one flag is to be modified, use \c GetGlobalOptions
-    /// to obtain the current set, modify the desired flag, then use \c SetGlobalOptions.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c SetGlobalOptions() updates the set of global option flags. There are none in this
+    /// version of the Toolkit.
+    ///
+    /// The entire set is replaced with the new values. If only one flag is to be modified, use
+    /// \c TXMPMeta::GetGlobalOptions() to obtain the current set, modify the desired flag, then use
+    /// this function to reset the value.
     ///
-    /// \note There are no options to set yet.
+    /// This function is static; you can make the call from the class without instantiating it.
+    ///
+    /// @param options A logical OR of global option bit-flag constants.
 
-    static void
-    SetGlobalOptions ( XMP_OptionBits options );
+    static void SetGlobalOptions ( XMP_OptionBits options );
 
     /// @}
 
-    //  --------------------------------------------------------------------------------------------
+    // ---------------------------------------------------------------------------------------------
     /// \name Internal data structure dump utilities
     /// @{
-    /// These are debugging utilities that dump internal data structures. The output callback is
-    /// described in <tt>XMP_Const.h</tt>.
+    ///
+    /// These are debugging utilities that dump internal data structures, to be handled by
+    /// client-defined callback described in \c XMP_Const.h.
+	///
+	/// @see Member function \c TXMPMeta::DumpObject()
 
-    /// \brief \c DumpNamespaces dumps the list of registered namespace URIs and prefixes.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c DumpNamespaces() sends the list of registered namespace URIs and prefixes to a handler.
+    ///
+    /// For debugging. Invokes a client-defined callback for each line of output.
+    ///
+    /// This function is static; make the call directly from the concrete class (\c SXMPMeta).
+    ///
+    /// @param outProc The client-defined procedure to handle each line of output.
+    ///
+    /// @param clientData A pointer to client-defined data to pass to the handler.
+    ///
+    /// @return	A success-fail status value, returned from the handler. Zero is success, failure
+    /// values are client-defined.
 
-    static XMP_Status
-    DumpNamespaces ( XMP_TextOutputProc outProc,
-                     void *             refCon );
+    static XMP_Status DumpNamespaces ( XMP_TextOutputProc outProc,
+                     				   void *             clientData );
 
-    /// \brief \c DumpAliases dumps the list of registered aliases and corresponding actuals.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c DumpAliases() sends the list of registered aliases and corresponding actuals to a handler.
+    ///
+    /// For debugging. Invokes a client-defined callback for each line of output.
+    ///
+    /// This function is static; make the call directly from the concrete class (\c SXMPMeta).
+    ///
+    /// @param outProc The client-defined procedure to handle each line of output.
+    ///
+    /// @param clientData A pointer to client-defined data to pass to the handler.
+    ///
+    /// @return	A success-fail status value, returned from the handler. Zero is success, failure
+    /// values are client-defined.
 
-    static XMP_Status
-    DumpAliases ( XMP_TextOutputProc outProc,
-                  void *             refCon );
+    static XMP_Status DumpAliases ( XMP_TextOutputProc outProc,
+                  					void *             clientData );
 
     /// @}
 
-    //  --------------------------------------------------------------------------------------------
+    // ---------------------------------------------------------------------------------------------
     /// \name Namespace Functions
     /// @{
+    ///
     /// Namespaces must be registered before use in namespace URI parameters or path expressions.
     /// Within the XMP Toolkit the registered namespace URIs and prefixes must be unique. Additional
     /// namespaces encountered when parsing RDF are automatically registered.
@@ -222,197 +266,204 @@ public:
     /// because some forms of RDF shorthand catenate a namespace URI with an element name to form a
     /// new URI.
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Register a namespace URI with a suggested prefix.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c RegisterNamespace() registers a namespace URI with a suggested prefix.
     ///
-    /// It is not an error if the URI is already registered, no matter what the prefix is. If the
-    /// URI is not registered but the suggested prefix is in use, a unique prefix is created from
-    /// the suggested one. The actual registeed prefix is always returned. The function result
-    /// tells if the registered prefix is the suggested one.
+    /// If the URI is not registered but the suggested prefix is in use, a unique prefix is created
+    /// from the suggested one. The actual registered prefix is returned. The function result tells
+    /// if the registered prefix is the suggested one. It is not an error if the URI is already
+    /// registered, regardless of the prefix.
     ///
-    /// \param namespaceURI The URI for the namespace. Must be a valid XML URI.
+    /// This function is static; make the call directly from the concrete class (\c SXMPMeta).
     ///
-    /// \param suggestedPrefix The suggested prefix to be used if the URI is not yet registered.
+    /// @param namespaceURI The URI for the namespace. Must be a valid XML URI.
+    ///
+    /// @param suggestedPrefix The suggested prefix to be used if the URI is not yet registered.
     /// Must be a valid XML name.
     ///
-    /// \param registeredPrefix Returns the prefix actually registered for this URI.
+    /// @param registeredPrefix [out] A string object in which to return the prefix actually
+    /// registered for this URI.
     ///
-    /// \result Returns true if the registered prefix matches the suggested prefix.
+    /// @return True if the registered prefix matches the suggested prefix.
     ///
-    /// \note No checking is presently done on either the URI or the prefix.
+    /// @note No checking is done on either the URI or the prefix.  */
 
-    static bool
-    RegisterNamespace ( XMP_StringPtr namespaceURI,
-                        XMP_StringPtr suggestedPrefix,
-                        tStringObj *  registeredPrefix );
+    static bool RegisterNamespace ( XMP_StringPtr namespaceURI,
+                        			XMP_StringPtr suggestedPrefix,
+                       				tStringObj *  registeredPrefix );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Obtain the prefix for a registered namespace URI.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c GetNamespacePrefix() obtains the prefix for a registered namespace URI, and
+    /// reports whether the URI is registered.
     ///
-    /// It is not an error if the namespace URI is not registered. The output \c namespacePrefix
-    /// string is not modified if the namespace URI is not registered.
+    /// This function is static; make the call directly from the concrete class (\c SXMPMeta).
     ///
-    /// \param namespaceURI The URI for the namespace. Must not be null or the empty string.
+    /// @param namespaceURI The URI for the namespace. Must not be null or the empty string. It is
+    /// not an error if the namespace URI is not registered.
     ///
-    /// \param namespacePrefix Returns the prefix registered for this URI, with a terminating ':'.
+    /// @param namespacePrefix [out] A string object in which to return the prefix registered for
+    /// this URI, with a terminating colon character, ':'. If the namespace is not registered, this
+    /// string is not modified.
     ///
-    /// \result Returns true if the namespace URI is registered.
+    /// @return True if the namespace URI is registered.
 
-    static bool
-    GetNamespacePrefix ( XMP_StringPtr namespaceURI,
-                         tStringObj *  namespacePrefix );
+    static bool GetNamespacePrefix ( XMP_StringPtr namespaceURI,
+                         			 tStringObj *  namespacePrefix );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Obtain the URI for a registered namespace prefix.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c GetNamespaceURI() obtains the URI for a registered namespace prefix, and reports
+    /// whether the prefix is registered.
     ///
-    /// It is not an error if the namespace prefix is not registered. The output \c namespaceURI
-    /// string is not modified if the namespace prefix is not registered.
+    /// This function is static; make the call directly from the concrete class (\c SXMPMeta).
     ///
-    /// \param namespacePrefix The prefix for the namespace. Must not be null or the empty string.
+    /// @param namespacePrefix The prefix for the namespace. Must not be null or the empty string.
+    /// It is not an error if the namespace prefix is not registered.
     ///
-    /// \param namespaceURI Returns the URI registered for this prefix.
+    /// @param namespaceURI [out] A string object in which to return the URI registered for this
+    /// prefix. If the prefix is not registered, this string is not modified.
     ///
-    /// \result Returns true if the namespace prefix is registered.
+    /// @return True if the namespace prefix is registered.
 
-    static bool
-    GetNamespaceURI ( XMP_StringPtr namespacePrefix,
-                      tStringObj *  namespaceURI );
+    static bool GetNamespaceURI ( XMP_StringPtr namespacePrefix,
+                      			  tStringObj *  namespaceURI );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Delete a namespace from the registry.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief Not implemented.
     ///
-    /// Does nothing if the URI is not registered, or if the \c namespaceURI parameter is null or the
-    /// empty string.
+    /// Deletes a namespace from the registry. Does nothing if the URI is not registered, or if the
+    /// parameter is null or the empty string.
     ///
-    /// \param namespaceURI The URI for the namespace.
+    /// This function is static; make the call directly from the concrete class (\c SXMPMeta).
     ///
-    /// \note <b>Not yet implemented.</b>
+    /// @param namespaceURI The URI for the namespace.
 
-    static void
-    DeleteNamespace ( XMP_StringPtr namespaceURI );
+    static void DeleteNamespace ( XMP_StringPtr namespaceURI );
 
     /// @}
 
-    //  --------------------------------------------------------------------------------------------
-    /// \name Alias Functions
+    // ---------------------------------------------------------------------------------------------
+    /// \name Alias functions
     /// @{
-    /// Aliases in XMP serve the same purpose as Windows file shortcuts, Macintosh file aliases, or
-    /// UNIX file symbolic links. The aliases are simply multiple names for the same property. One
-    /// distinction of XMP aliases is that they are ordered, there is an alias name pointing to an
-    /// actual name. The primary significance of the actual name is that it is the preferred name
-    /// for output, generally the most widely recognized name.
-    ///
-    /// The names that can be aliased in XMP are restricted. The alias must be a top level property
-    /// name, not a field within a structure or an element within an array. The actual may be a top
-    /// level property name, the first element within a top level array, or the default element in
-    /// an alt-text array. This does not mean the alias can only be a simple property. It is OK to
-    /// alias a top level structure or array to an identical top level structure or array, or to the
-    /// first item of an array of structures.
-
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Associates an alias name with an actual name.
-    ///
-    /// Define a alias mapping from one namespace/property to another. Both property names must be
+    ///
+    /// Aliases in XMP serve the same purpose as Windows file shortcuts, Mac OS file aliases, or
+    /// UNIX file symbolic links. The aliases are multiple names for the same property. One
+    /// distinction of XMP aliases is that they are ordered. An alias name points to an actual name;
+    /// the primary significance of the actual name is that it is the preferred name for output,
+    /// generally the most widely recognized name.
+    ///
+    /// XMP restricts the names that can be aliased. The alias must be a top-level property name,
+    /// not a field within a structure or an element within an array. The actual can be a top-level
+    /// property name, the first element within a top-level array, or the default element in an
+    /// alt-text array. This does not mean the alias can only be a simple property; you can alias a
+    /// top-level structure or array to an identical top-level structure or array, or to the first
+    /// item of an array of structures.
+
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c RegisterAlias() associates an alias name with an actual name.
+    ///
+    /// Defines an alias mapping from one namespace/property to another. Both property names must be
     /// simple names. An alias can be a direct mapping, where the alias and actual have the same
     /// data type. It is also possible to map a simple alias to an item in an array. This can either
     /// be to the first item in the array, or to the 'x-default' item in an alt-text array. Multiple
-    /// alias names may map to the same actual, as long as the forms match. It is a no-op to
+    /// alias names can map to the same actual, as long as the forms match. It is a no-op to
     /// reregister an alias in an identical fashion.
     ///
-    /// \param aliasNS The namespace URI for the alias. Must not be null or the empty string.
+    /// This function is static; make the call directly from the concrete class (\c SXMPMeta).
+    ///
+    /// @param aliasNS The namespace URI for the alias. Must not be null or the empty string.
     ///
-    /// \param aliasProp The name of the alias. Must be a simple name, not null or the empty string
+    /// @param aliasProp The name of the alias. Must be a simple name, not null or the empty string
     /// and not a general path expression.
     ///
-    /// \param actualNS The namespace URI for the actual. Must not be null or the empty string.
+    /// @param actualNS The namespace URI for the actual. Must not be null or the empty string.
     ///
-    /// \param actualProp The name of the actual. Must be a simple name, not null or the empty string
+    /// @param actualProp The name of the actual. Must be a simple name, not null or the empty string
     /// and not a general path expression.
     ///
-    /// \param arrayForm Provides the array form for simple aliases to an array item. This is needed
+    /// @param arrayForm Provides the array form for simple aliases to an array item. This is needed
     /// to know what kind of array to create if set for the first time via the simple alias. Pass
-    /// \c kXMP_NoOptions, the default value, for all direct aliases regardless of whether the actual
-    /// data type is an array or not.
-    ///
-    /// Constants for the arrayForm parameter:
-    ///
-    /// \li \c kXMP_NoOptions - This is a direct mapping. The actual data type does not matter.
-    /// \li \c kXMP_PropValueIsArray - The actual is an unordered array, the alias is to the first
-    /// element of the array.
-    /// \li \c kXMP_PropArrayIsOrdered - The actual is an ordered array, the alias is to the first
-    /// element of the array.
-    /// \li \c kXMP_PropArrayIsAlternate - The actual is an alternate array, the alias is to the first
-    /// element of the array.
-    /// \li \c kXMP_PropArrayIsAltText - The actual is an alternate text array, the alias is to the
-    /// 'x-default' element of the array.
-
-    static void
-    RegisterAlias ( XMP_StringPtr  aliasNS,
-                    XMP_StringPtr  aliasProp,
-                    XMP_StringPtr  actualNS,
-                    XMP_StringPtr  actualProp,
-                    XMP_OptionBits arrayForm = kXMP_NoOptions );
-
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Determines if a name is an alias, and what it is aliased to.
-    ///
-    /// \param aliasNS The namespace URI for the alias. Must not be null or the empty string.
-    ///
-    /// \param aliasProp The name of the alias. May be an arbitrary path expression path, must not
+    /// \c #kXMP_NoOptions, the default value, for all direct aliases regardless of whether the actual
+    /// data type is an array or not. One of these constants:
+    ///
+    ///   \li \c #kXMP_NoOptions - This is a direct mapping. The actual data type does not matter.
+    ///   \li \c #kXMP_PropValueIsArray - The actual is an unordered array, the alias is to the
+    ///   first element of the array.
+    ///   \li \c #kXMP_PropArrayIsOrdered - The actual is an ordered array, the alias is to the
+    ///   first element of the array.
+    ///   \li \c #kXMP_PropArrayIsAlternate - The actual is an alternate array, the alias is to the
+    ///   first element of the array.
+    ///   \li \c #kXMP_PropArrayIsAltText - The actual is an alternate text array, the alias is to
+    ///   the 'x-default' element of the array.  */
+
+    static void RegisterAlias ( XMP_StringPtr  aliasNS,
+                    			XMP_StringPtr  aliasProp,
+                    			XMP_StringPtr  actualNS,
+                    			XMP_StringPtr  actualProp,
+                    			XMP_OptionBits arrayForm = kXMP_NoOptions );
+
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c ResolveAlias() reports whether a name is an alias, and what it is aliased to.
+    ///
+    /// Output strings are not written until return, so you can use this to
+    /// "reduce" a path to the base form as follows:
+    /// <pre>
+    ///   isAlias = SXMPMeta::ResolveAlias ( ns.c_str(), path.c_str(), &ns, &path, 0 );
+    /// </pre>
+    /// This function is static; make the call directly from the concrete class (\c SXMPMeta).
+    ///
+    /// @param aliasNS The namespace URI for the alias. Must not be null or the empty string.
+    ///
+    /// @param aliasProp The name of the alias. Can be an arbitrary path expression path, must not
     /// null or the empty string.
     ///
-    /// \param actualNS Untouched if <tt>aliasNS:aliasProp</tt> is not an alias. Otherwise returns
-    /// the namespace URI for the actual. May be null if the namespace URI is not wanted.
+    /// @param actualNS  [out] A string object in which to return the namespace URI for the actual.
+    /// Not modified if the given name is not an alias. Can be null if the namespace URI is not wanted.
     ///
-    /// \param actualProp Untouched if <tt>aliasNS:aliasProp</tt> is not an alias. Otherwise
-    /// returns the path of the actual. May be null if the actual's path is not wanted.
+    /// @param actualProp  [out] A string object in which to return the path of the actual.
+    /// Not modified if the given name is not an alias. Can be null if the actual's path is not wanted.
     ///
-    /// \param arrayForm Untouched if <tt>aliasNS:aliasProp</tt> is not an alias. Otherwise returns
-    /// the form of the actual. This is 0 (\c kXMP_NoOptions) if the alias and actual forms match,
-    /// otherwise it is the options passed to <tt>TXMPMeta::RegisterAlias</tt>. May be null if the
-    /// actual's form is not wanted.
+    /// @param arrayForm [out] A string object in which to return the array form of the actual. This
+    /// is 0 (\c #kXMP_NoOptions) if the alias and actual forms match, otherwise it is the options
+    /// passed to \c TXMPMeta::RegisterAlias(). Not modified if the given name is not an alias. Can
+    /// be null if the actual's array form is not wanted.
     ///
-    /// \result Returns true if the input is an alias.
-    ///
-    /// \note The client output strings are not written until return, so a call like the following
-    /// may be used to "reduce" a path to the base form:
-    /// \code
-    ///  isAlias = SXMPMeta::ResolveAlias ( ns.c_str(), path.c_str(), &ns, &path, 0 );
-    /// \endcode
+    /// @return True if the provided name is an alias.
 
-    static bool
-    ResolveAlias ( XMP_StringPtr    aliasNS,
-                   XMP_StringPtr    aliasProp,
-                   tStringObj *     actualNS,
-                   tStringObj *     actualProp,
-                   XMP_OptionBits * arrayForm );
+    static bool ResolveAlias ( XMP_StringPtr    aliasNS,
+                   			   XMP_StringPtr    aliasProp,
+                  			   tStringObj *     actualNS,
+                 			   tStringObj *     actualProp,
+                 			   XMP_OptionBits * arrayForm );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Delete an alias.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c DeleteAlias() deletes an alias.
     ///
-    /// This only deletes the registration of the alias, it does not delete the actual property. It
-    /// does delete any view of the property through the alias name. It is OK to attempt to delete
-    /// an alias that does not exist, that is if the alias name is not registered as an alias.
+    /// This deletes only the registration of the alias, it does not delete the actual property.
+    /// It deletes any view of the property through the alias name.
     ///
-    /// \param aliasNS The namespace URI for the alias. Must not be null or the empty string.
+    /// This function is static; make the call directly from the concrete class (\c SXMPMeta).
     ///
-    /// \param aliasProp The name of the alias. Must be a simple name, not null or the empty string
-    /// and not a general path expression.
+    /// @param aliasNS The namespace URI for the alias. Must not be null or the empty string.
+    ///
+    /// @param aliasProp The name of the alias. Must be a simple name, not null or the empty string
+    /// and not a general path expression. It is not an error to provide
+    /// a name that has not been registered as an alias.
 
-    static void
-    DeleteAlias ( XMP_StringPtr aliasNS,
-                  XMP_StringPtr aliasProp );
+    static void DeleteAlias ( XMP_StringPtr aliasNS,
+                  			  XMP_StringPtr aliasProp );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Registers all of the built-in aliases for a standard namespace.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c RegisterStandardAliases() registers all of the built-in aliases for a standard namespace.
+    ///
+    /// The built-in aliases are documented in the XMP Specification. This function registers the
+    /// aliases in the given namespace; that is, it creates the aliases from this namespace to
+    /// actuals in other namespaces.
     ///
-    /// The built-in aliases are documented in the XMP Specification. This registers the aliases in
-    /// the given namespace, that is the aliases from this namespace to actuals in other namespaces.
+    /// This function is static; make the call directly from the concrete class (\c SXMPMeta).
     ///
-    /// \param schemaNS The namespace URI for the aliases. Must not be null or the empty string.
+    /// @param schemaNS The namespace URI for the aliases. Must not be null or the empty string.
 
-    static void
-    RegisterStandardAliases ( XMP_StringPtr schemaNS );
+    static void RegisterStandardAliases ( XMP_StringPtr schemaNS );
 
     /// @}
 
@@ -422,1164 +473,1327 @@ public:
 
     // *** Should add discussion of schemaNS and propName prefix usage.
 
-    //  --------------------------------------------------------------------------------------------
-    /// \name Functions for getting property values
+    // ---------------------------------------------------------------------------------------------
+    /// \name Accessing property values
     /// @{
-    /// The property value "getters" all take a property specification, The first two parameters
-    /// are always the top level namespace URI (the "schema" namespace) and the basic name of the
-    /// property being referenced. See the introductory discussion of path expression usage for
-    /// more information.
     ///
-    /// All of the functions return a Boolean result telling if the property exists, and if it does
-    /// they also return option flags describing the property. If the property exists and has a
-    /// value, the string value is also returned. The string is Unicode in UTF-8 encoding. Arrays
-    /// and the non-leaf levels of structs do not have values. The possible option flags that
-    /// describe properties are:
+    /// The property value accessors all take a property specification; the top level namespace URI
+    ///	(the "schema" namespace) and the basic name of the property being referenced. See the
+    ///	introductory discussion of path expression usage for more information.
+	///
+    /// The accessor functions return true if the specified property exists. If it does, output
+    /// parameters return the value (if any) and option flags describing the property. The option
+    /// bit-flag constants that describe properties are \c kXMP_PropXx and
+	/// \c kXMP_ArrayIsXx. See \c #kXMP_PropValueIsURI and following, and macros \c #XMP_PropIsSimple
+	/// and following in \c XMP_Const.h. If the property exists and has a value, it is returned as a
+	/// Unicode string in UTF-8 encoding. Arrays and the non-leaf levels of structs do not have
+	/// values.
+
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c GetProperty() reports whether a property exists, and retrieves its value.
+    ///
+    /// This is the simplest property accessor. Use this to retrieve the values of top-level simple
+    /// properties, or after using the path composition functions in \c TXMPUtils.
+    ///
+    /// When specifying a namespace and path (in this and all other accessors):
+    ///   \li If a namespace URI is specified, it must be for a registered namespace.
+    ///   \li If the namespace is specified only by a prefix in the property name path,
+    /// it must be a registered prefix.
+    ///   \li If both a URI and path prefix are present, they must be corresponding
+    /// parts of a registered namespace.
+    ///
+    /// @param schemaNS The namespace URI for the property. The URI must be for a registered
+    /// namespace. Can be null or the empty string if the first component of the \c propName path
+    /// contains a namespace prefix.
+    ///
+    /// @param propName The name of the property. Can be a general path expression, must not be null
+    /// or the empty string. The first component can be a namespace prefix; if present without a
+    /// \c schemaNS value, the prefix specifies the namespace. The prefix must be for a registered
+    /// namespace, and if a namespace URI is specified, must match the registered prefix for that
+    /// namespace.
     ///
-    /// \li \c kXMP_PropValueIsURI - The property value is a URI. It is serialized to RDF using the
-    /// <tt>rdf:resource</tt> attribute. Not mandatory for URIs, but considered RDF-savvy.
+    /// @param propValue [out] A string object in which to return the value of the property, if the
+    /// property exists and has a value. Arrays and non-leaf levels of structs do not have values.
+    /// Can be null if the value is not wanted.
     ///
-    /// \li \c kXMP_PropHasQualifiers - The property has qualifiers. These could be an
-    /// <tt>xml:lang</tt> attribute, an <tt>rdf:type</tt> property, or a general qualifier. See the
-    /// introductory discussion of qualified properties for more information.
+    /// @param options A buffer in which to return option flags describing the property. Can be null
+    /// if the flags are not wanted.
     ///
-    /// \li \c kXMP_PropIsQualifier - This property is a qualifier for some other property. Note
-    /// that if the qualifier itself has a structured value, this flag is only set for the top node
-    /// of the qualifier's subtree. Qualifiers may have arbitrary structure, and may even have
-    /// qualifiers.
+    /// @return True if the property exists.
+
+    bool GetProperty ( XMP_StringPtr    schemaNS,
+                 	   XMP_StringPtr    propName,
+                       tStringObj *     propValue,
+                  	   XMP_OptionBits * options ) const;
+
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c GetArrayItem() provides access to items within an array.
+    ///
+    /// Reports whether the item exists; if it does, and if it has a value, the function retrieves
+    /// the value. Items are accessed by an integer index, where the first item has index 1.
+    ///
+    /// @param schemaNS The namespace URI for the array; see \c GetProperty().
     ///
-    /// \li \c kXMP_PropHasLang - This property has an <tt>xml:lang</tt> qualifier.
+    /// @param arrayName The name of the array. Can be a general path expression, must not be null
+    /// or the empty string; see \c GetProperty() for namespace prefix usage.
     ///
-    /// \li \c kXMP_PropHasType - This property has an <tt>rdf:type</tt> qualifier.
+    /// @param itemIndex The 1-based index of the desired item. Use the macro \c #kXMP_ArrayLastItem
+    /// to specify the last existing array item.
     ///
-    /// \li \c kXMP_PropValueIsStruct - This property contains nested fields (models a C struct).
+    /// @param itemValue [out] A string object in which to return the value of the array item, if it
+    /// has a value. Arrays and non-leaf levels of structs do not have values. Can be null if the
+    /// value is not wanted.
     ///
-    /// \li \c kXMP_PropValueIsArray - This property is an array. By itself (no ...ArrayIs... flags),
-    /// this indicates a general unordered array. It is serialized using an <tt>rdf:Bag</tt> container.
+    /// @param options [out] A buffer in which to return the option flags describing the array item.
+    /// Can be null if the flags are not wanted.
     ///
-    /// \li \c kXMP_PropArrayIsOrdered - This property is an ordered array. Appears in conjunction
-    /// with \c kXMP_PropValueIsArray. It is serialized using an <tt>rdf:Seq</tt> container.
+    /// @return True if the array item exists.
+
+    bool GetArrayItem ( XMP_StringPtr    schemaNS,
+                   		XMP_StringPtr    arrayName,
+                   		XMP_Index        itemIndex,
+                   		tStringObj *     itemValue,
+                   		XMP_OptionBits * options ) const;
+
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c GetStructField() provides access to fields within a nested structure.
     ///
-    /// \li \c kXMP_PropArrayIsAlternate - This property is an alternative array. Appears in
-    /// conjunction with \c kXMP_PropValueIsArray. It is serialized using an <tt>rdf:Alt</tt> container.
+    /// Reports whether the field exists; if it does, and if it has a value, the function retrieves
+    /// the value.
     ///
-    /// \li \c kXMP_PropArrayIsAltText - This property is an alt-text array. Appears in conjunction
-    /// with \c kXMP_PropArrayIsAlternate. It is serialized using an <tt>rdf:Alt</tt> container. Each
-    /// array element is a simple property with an <tt>xml:lang</tt> attribute.
+    /// @param schemaNS The namespace URI for the struct; see \c GetProperty().
     ///
-    /// \li \c kXMP_PropIsAlias - The given property name is an alias. This is only returned by
-    /// \c GetProperty and then only if the property name is simple, not an path expression.
+    /// @param structName The name of the struct. Can be a general path expression, must not be null
+    /// or the empty string; see \c GetProperty() for namespace prefix usage.
     ///
-    /// \li \c kXMP_PropHasAliases - The given property name has aliases. This is only returned by
-    /// \c GetProperty and then only if the property name is simple, not an path expression.
+    /// @param fieldNS The namespace URI for the field. Same URI and prefix usage as the \c schemaNS
+    /// and \c structName parameters.
     ///
-    /// \li \c kXMP_PropIsStable - The value of this property is not related to the document
-    /// content.
+    /// @param fieldName The name of the field. Must be a single XML name, must not be null or the
+    /// empty string. Same URI and prefix usage as the \c schemaNS and \c structName parameters.
     ///
-    /// \li \c kXMP_PropIsDerived -  The value of this property is derived from the document
-    /// content.
+    /// @param fieldValue [out] A string object in which to return the value of the field, if the
+    /// field has a value. Arrays and non-leaf levels of structs do not have values. Can be null if
+    /// the value is not wanted.
     ///
-    /// \li \c kXMP_PropIsInternal - The value of this property is "owned" by the application, it
-    /// should not generally be editable in a UI.
+    /// @param options [out] A buffer in which to return the option flags describing the field. Can
+    /// be null if the flags are not wanted.
+    ///
+    /// @return True if the field exists.
+
+    bool GetStructField ( XMP_StringPtr    schemaNS,
+                     	  XMP_StringPtr    structName,
+                     	  XMP_StringPtr    fieldNS,
+                     	  XMP_StringPtr    fieldName,
+                     	  tStringObj *     fieldValue,
+                     	  XMP_OptionBits * options ) const;
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief \c GetProperty is the simplest property getter, mainly for top level simple
-    /// properties or after using the path composition functions in \c TXMPUtils.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c GetQualifier() provides access to a qualifier attached to a property.
     ///
-    /// \result Returns true if the property exists.
+    /// @note In this version of the Toolkit, qualifiers are supported only for simple leaf properties.
     ///
-    /// \param schemaNS The namespace URI for the property. May be null or the empty string if the
-    /// first component of the propName path contains a namespace prefix. The URI must be for a
-    /// registered namespace.
+    /// @param schemaNS The namespace URI; see \c GetProperty().
     ///
-    /// \param propName The name of the property. May be a general path expression, must not be
-    /// null or the empty string. Using a namespace prefix on the first component is optional. If
-    /// present without a \c schemaNS value then the prefix specifies the namespace. The prefix
-    /// must be for a registered namespace. If both a \c schemaNS URI and \c propName prefix are
-    /// present, they must be corresponding parts of a registered namespace.
+    /// @param propName The name of the property to which the qualifier is attached. Can be a
+    /// general path expression, must not be null or the empty string; see \c GetProperty() for
+    /// namespace prefix usage.
     ///
-    /// \param propValue A pointer to the string that is assigned the value of the property, if
-    /// the property has a value. Arrays and non-leaf levels of structs do not have values. May be
-    /// null if the value is not wanted.
+    /// @param qualNS The namespace URI for the qualifier. Same URI and prefix usage as the
+    /// \c schemaNS and \c propName parameters.
     ///
-    /// \param options A pointer to the \c XMP_OptionBits variable that is assigned option flags
-    /// describing the property. May be null if the flags are not wanted.
+    /// @param qualName The name of the qualifier. Must be a single XML name, must not be null or
+    /// the empty string. Same URI and prefix usage as the \c schemaNS and \c propName parameters.
+    ///
+    /// @param qualValue [out] A string object in which to return the value of the qualifier, if the
+    /// qualifier has a value. Arrays and non-leaf levels of structs do not have values. Can be null
+    /// if the value is not wanted.
+    ///
+    /// @param options [out] A buffer in which to return the option flags describing the qualifier.
+    /// Can be null if the flags are not wanted.
+    ///
+    /// @return True if the qualifier exists.
+
+    bool GetQualifier ( XMP_StringPtr    schemaNS,
+                   		XMP_StringPtr    propName,
+                  		XMP_StringPtr    qualNS,
+                  		XMP_StringPtr    qualName,
+                   		tStringObj *     qualValue,
+                   		XMP_OptionBits * options ) const;
 
-    bool
-    GetProperty ( XMP_StringPtr    schemaNS,
-                  XMP_StringPtr    propName,
-                  tStringObj *     propValue,
-                  XMP_OptionBits * options ) const;
+    /// @}
+
+    // =============================================================================================
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief \c GetArrayItem provides access to items within an array. The index is passed as an
-    /// integer, you need not worry about the path string syntax for array items, convert a loop
-    /// index to a string, etc.
+    // ---------------------------------------------------------------------------------------------
+    /// \name Creating properties and setting their values
+ 	/// @{
+ 	///
+    /// These functions all take a property specification; the top level namespace URI (the "schema"
+    /// namespace) and the basic name of the property being referenced. See the introductory
+    /// discussion of path expression usage for more information.
+	///
+    /// All of the functions take a UTF-8 encoded Unicode string for the property value. Arrays and
+    /// non-leaf levels of structs do not have values. The value can be passed as an
+    /// \c #XMP_StringPtr (a pointer to a null-terminated string), or as a string object
+    /// (\c tStringObj).
+
+    /// Each function takes an options flag that describes the property. You can use these functions
+    /// to create empty arrays and structs by setting appropriate option flags. When you assign a
+    /// value, all levels of a struct that are implicit in the assignment are created if necessary.
+    /// \c TXMPMeta::AppendArrayItem() implicitly creates the named array if necessary.
     ///
-    /// \result Returns true if the array item exists.
+    /// The allowed option bit-flags include:
+    ///   \li \c #kXMP_PropValueIsStruct - Can be used to create an empty struct.
+    ///		A struct is implicitly created when the first field is set.
+    ///   \li \c #kXMP_PropValueIsArray - By default, a general unordered array (bag).
+    ///   \li \c #kXMP_PropArrayIsOrdered - An ordered array.
+   	///   \li \c #kXMP_PropArrayIsAlternate - An alternative array.
+   	///   \li \c #kXMP_PropArrayIsAltText - An alt-text array. Each array element must
+    /// 	be a simple property with an \c xml:lang attribute.
+
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c SetProperty() creates or sets a property value.
     ///
-    /// \param schemaNS The namespace URI for the array. Has the same usage as in \c GetProperty.
+    /// This is the simplest property setter. Use it for top-level simple properties, or after using
+    /// the path composition functions in \c TXMPUtils.
     ///
-    /// \param arrayName The name of the array. May be a general path expression, must not be null
-    /// or the empty string. Has the same namespace prefix usage as \c propName in \c GeProperty.
+    /// @param schemaNS The namespace URI; see \c GetProperty().
     ///
-    /// \param itemIndex The index of the desired item. Arrays in XMP are indexed from 1. The constant
-    /// \c kXMP_ArrayLastItem always refers to the last existing array item.
+    /// @param propName The name of the property. Can be a general path expression, must not be null
+    /// or the empty string; see \c GetProperty() for namespace prefix usage.
     ///
-    /// \param itemValue A pointer to the string that is assigned the value of the array item, if
-    /// the array item has a value. Arrays and non-leaf levels of structs do not have values. May be
-    /// null if the value is not wanted.
+    /// @param propValue The new value, a pointer to a null terminated UTF-8 string. Must be null
+    /// for arrays and non-leaf levels of structs that do not have values.
     ///
-    /// \param options A pointer to the \c XMP_OptionBits variable that is assigned option flags
-    /// describing the array item. May be null if the flags are not wanted.
+    /// @param options Option flags describing the property; a logical OR of allowed bit-flag
+    /// constants; see \c #kXMP_PropValueIsStruct and following. Must match the type of a property
+    /// that already exists.
+
+    void SetProperty ( XMP_StringPtr  schemaNS,
+					   XMP_StringPtr  propName,
+					   XMP_StringPtr  propValue,
+					   XMP_OptionBits options = 0 );
 
-    bool
-    GetArrayItem ( XMP_StringPtr    schemaNS,
-                   XMP_StringPtr    arrayName,
-                   XMP_Index        itemIndex,
-                   tStringObj *     itemValue,
-                   XMP_OptionBits * options ) const;
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c SetProperty() creates or sets a property value using a string object.
+	///
+    /// Overloads the basic form of the function, allowing you to pass a string object
+	/// for the item value. It is otherwise identical; see details in the canonical form.
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief \c GetStructField provides access to fields within a nested structure. The namespace
-    /// for the field is passed as a URI, you need not worry about the path string syntax.
+    void SetProperty ( XMP_StringPtr      schemaNS,
+					   XMP_StringPtr      propName,
+					   const tStringObj & propValue,
+					   XMP_OptionBits     options = 0 );
+
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c SetArrayItem() creates or sets the value of an item within an array.
     ///
-    /// The names of fields should be XML qualified names, that is within an XML namespace. The path
-    /// syntax for a qualified name uses the namespace prefix. This is unreliable since the prefix
-    /// is never guaranteed. The URI is the formal name, the prefix is just a local shorthand in a
-    /// given sequence of XML text.
+    /// Items are accessed by an integer index, where the first item has index 1. This function
+    /// creates the item if necessary, but the array itself must already exist Use
+    /// \c AppendArrayItem() to create arrays. A new item is automatically appended if the index is the
+    /// array size plus 1. To insert a new item before or after an existing item, use option flags.
     ///
-    /// \result Returns true if the field exists.
+    /// Use \c TXMPUtils::ComposeArrayItemPath() to create a complex path.
     ///
-    /// \param schemaNS The namespace URI for the struct. Has the same usage as in \c GetProperty.
+    /// @param schemaNS The namespace URI; see \c GetProperty().
     ///
-    /// \param structName The name of the struct. May be a general path expression, must not be null
-    /// or the empty string. Has the same namespace prefix usage as \c propName in \c GetProperty.
+    /// @param arrayName The name of the array. Can be a general path expression, must not be null
+    /// or the empty string; see \c GetProperty() for namespace prefix usage.
     ///
-    /// \param fieldNS The namespace URI for the field. Has the same URI and prefix usage as the
-    /// \c schemaNS parameter.
+    /// @param itemIndex The 1-based index of the desired item. Use the macro \c #kXMP_ArrayLastItem
+    /// to specify the last existing array item.
     ///
-    /// \param fieldName The name of the field. Must be a single XML name, must not be null or the
-    /// empty string. Has the same namespace prefix usage as the \c structName parameter.
+    /// @param itemValue The new item value, a null-terminated UTF-8 string, if the array item has a
+    /// value.
     ///
-    /// \param fieldValue A pointer to the string that is assigned the value of the field, if
-    /// the field has a value. Arrays and non-leaf levels of structs do not have values. May be
-    /// null if the value is not wanted.
+    /// @param options Option flags describing the array type and insertion location for a new item;
+    /// a logical OR of allowed bit-flag constants. The type, if specified, must match the existing
+    /// array type, \c #kXMP_PropArrayIsOrdered, \c #kXMP_PropArrayIsAlternate, or
+    /// \c #kXMP_PropArrayIsAltText. Default (0 or \c #kXMP_NoOptions) matches the  existing array type.
     ///
-    /// \param options A pointer to the \c XMP_OptionBits variable that is assigned option flags
-    /// describing the field. May be null if the flags are not wanted.
+    /// To insert a new item before or after the specified index, set flag \c #kXMP_InsertBeforeItem
+    /// or \c #kXMP_InsertAfterItem.
 
-    bool
-    GetStructField ( XMP_StringPtr    schemaNS,
-                     XMP_StringPtr    structName,
-                     XMP_StringPtr    fieldNS,
-                     XMP_StringPtr    fieldName,
-                     tStringObj *     fieldValue,
-                     XMP_OptionBits * options ) const;
+    void SetArrayItem ( XMP_StringPtr  schemaNS,
+					    XMP_StringPtr  arrayName,
+					    XMP_Index      itemIndex,
+					    XMP_StringPtr  itemValue,
+					    XMP_OptionBits options = 0 );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief \c GetQualifier provides access to a qualifier attached to a property. The namespace
-    /// for the qualifier is passed as a URI, you need not worry about the path string syntax. In
-    /// many regards qualifiers are like struct fields. See the introductory discussion of
-    /// qualified properties for more information.
-    ///
-    /// The names of qualifiers should be XML qualified names, that is within an XML namespace. The
-    /// path syntax for a qualified name uses the namespace prefix. This is unreliable since the
-    /// prefix is never guaranteed. The URI is the formal name, the prefix is just a local shorthand
-    /// in a given sequence of XML text.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c SetArrayItem() creates or sets the value of an item within an array using a string object.
     ///
-    /// \note Qualifiers are only supported for simple leaf properties at this time.
+    /// Overloads the basic form of the function, allowing you to pass a string object in which to
+	/// return the item value. It is otherwise identical; see details in the canonical form.
+
+    void SetArrayItem ( XMP_StringPtr      schemaNS,
+					    XMP_StringPtr      arrayName,
+					    XMP_Index          itemIndex,
+					    const tStringObj & itemValue,
+					    XMP_OptionBits     options = 0 );
+
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c AppendArrayItem() adds an item to an array, creating the array if necessary.
     ///
-    /// \result Returns true if the qualifier exists.
+    /// This function simplifies construction of an array by not requiring that you pre-create an
+    /// empty array. The array that is assigned is created automatically if it does not yet exist.
+    /// If the array exists, it must have the form specified by the options. Each call appends a new
+    /// item to the array.
     ///
-    /// \param schemaNS The namespace URI for the struct. Has the same usage as in \c GetProperty.
+    /// Use \c TXMPUtils::ComposeArrayItemPath() to create a complex path.
     ///
-    /// \param propName The name of the property to which the qualifier is attached. May be a general
-    /// path expression, must not be null or the empty string. Has the same namespace prefix usage
-    /// as in \c GetProperty.
+    /// @param schemaNS The namespace URI; see \c GetProperty().
     ///
-    /// \param qualNS The namespace URI for the qualifier. Has the same URI and prefix usage as the
-    /// \c schemaNS parameter.
+    /// @param arrayName The name of the array. Can be a general path expression, must not be null
+    /// or the empty string; see \c GetProperty() for namespace prefix usage.
     ///
-    /// \param qualName The name of the qualifier. Must be a single XML name, must not be null or the
-    /// empty string. Has the same namespace prefix usage as the \c propName parameter.
+    /// @param arrayOptions Option flags describing the array type to create; a logical OR of
+    /// allowed bit-flag constants, \c #kXMP_PropArrayIsOrdered, \c #kXMP_PropArrayIsAlternate, or
+    /// \c #kXMP_PropArrayIsAltText. If the array exists, must match the existing array type or be
+    /// null (0 or \c #kXMP_NoOptions).
     ///
-    /// \param qualValue A pointer to the string that is assigned the value of the qualifier, if
-    /// the qualifier has a value. Arrays and non-leaf levels of structs do not have values. May be
-    /// null if the value is not wanted.
+    /// @param itemValue The new item value, a null-terminated UTF-8 string, if the array item has a
+    /// value.
     ///
-    /// \param options A pointer to the \c XMP_OptionBits variable that is assigned option flags
-    /// describing the qualifier. May be null if the flags are not wanted.
+    /// @param itemOptions Option flags describing the item type to create; one of the bit-flag
+    /// constants \c #kXMP_PropValueIsArray or \c #kXMP_PropValueIsStruct to create a complex array
+    /// item.
 
-    bool
-    GetQualifier ( XMP_StringPtr    schemaNS,
-                   XMP_StringPtr    propName,
-                   XMP_StringPtr    qualNS,
-                   XMP_StringPtr    qualName,
-                   tStringObj *     qualValue,
-                   XMP_OptionBits * options ) const;
+    void AppendArrayItem ( XMP_StringPtr  schemaNS,
+						   XMP_StringPtr  arrayName,
+						   XMP_OptionBits arrayOptions,
+						   XMP_StringPtr  itemValue,
+						   XMP_OptionBits itemOptions = 0 );
 
-    /// @}
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c AppendArrayItem() adds an item to an array using a string object value, creating
+    /// the array if necessary.
+    ///
+    /// Overloads the basic form of the function, allowing you to pass a string object in which to
+	/// return the item value. It is otherwise identical; see details in the canonical form.
 
-    // =============================================================================================
+    void AppendArrayItem ( XMP_StringPtr      schemaNS,
+						   XMP_StringPtr      arrayName,
+						   XMP_OptionBits     arrayOptions,
+						   const tStringObj & itemValue,
+						   XMP_OptionBits     itemOptions = 0 );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \name Functions for setting property values
- 	/// @{
-    /// The property value "setters" all take a property specification, their differences are in
-    /// the form of this. The first two parameters are always the top level namespace URI (the
-    /// "schema" namespace) and the basic name of the property being referenced. See the
-    /// introductory discussion of path expression usage for more information.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c SetStructField() creates or sets the value of a field within a nested structure.
     ///
-    /// All of the functions take a string value for the property and option flags describing the
-    /// property. The value must be Unicode in UTF-8 encoding. Arrays and non-leaf levels of
-    /// structs do not have values. Empty arrays and structs may be created using appropriate
-    /// option flags. All levels of structs that is assigned implicitly are created if necessary.
-    /// \c AppendArayItem implicitly creates the named array if necessary.
+    /// Use this to  set a value within an existing structure, create a new field within an existing
+    /// structure, or create an empty structure of any depth. If you set a field in a structure that
+    /// does not exist, the structure is automatically created.
     ///
-    /// The canonical form of these functions take the value as an \c XMP_StringPtr, a pointer to a
-    /// null terminated string. (\c XMP_StringPtr is a typedef for <tt>const char *</tt>.) They
-    /// also have overloaded forms that take a string object. These are implemented in the template
-    /// instantiation as a call to the canonical form, using <tt>value.c_str()</tt> to obtain the
-    /// \c XMP_StringPtr.
+    /// Use \c TXMPUtils::ComposeStructFieldPath() to create a complex path.
     ///
-    /// The possible option flags are:
+    /// @param schemaNS The namespace URI; see \c GetProperty().
     ///
-    /// \li \c kXMP_PropValueIsURI - The property value is a URI. It is serialized to RDF using the
-    /// <tt>rdf:resource</tt> attribute. Not mandatory for URIs, but considered RDF-savvy.
-    ///
-    /// \li \c kXMP_PropValueIsStruct - This property contains nested fields (models a C struct).
-    /// Not necessary, may be used to create an empty struct. A struct is implicitly created when
-    /// first field is set.
+    /// @param structName The name of the struct. Can be a general path expression, must not be null
+    /// or the empty string; see \c GetProperty() for namespace prefix usage.
     ///
-    /// \li \c kXMP_PropValueIsArray - This property is an array. By itself (no ...ArrayIs...
-    /// flags), this indicates a general unordered array. It is serialized using an
-    /// <tt>rdf:Bag</tt> container.
+    /// @param fieldNS The namespace URI for the field. Same namespace and prefix usage as
+    /// \c GetProperty().
     ///
-    /// \li \c kXMP_PropArrayIsOrdered - This property is an ordered array. Implies \c
-    /// kXMP_PropValueIsArray, may be used together. It is serialized using an <tt>rdf:Seq</tt>
-    /// container.
+    /// @param fieldName The name of the field. Must be a single XML name, must not be null or the
+    /// empty string. Same namespace and prefix usage as \c GetProperty().
     ///
-    /// \li \c kXMP_PropArrayIsAlternate - This property is an alternative array. Implies \c
-    /// kXMP_PropArrayIsOrdered, may be used together. It is serialized using an <tt>rdf:Alt</tt>
-    /// container.
+    /// @param fieldValue The new value, a null-terminated UTF-8 string, if the field has a value.
+    /// Null to create a new, empty struct or empty field in an existing struct.
     ///
-    /// \li \c kXMP_PropArrayIsAltText - This property is an alt-text array. Implies \c
-    /// kXMP_PropArrayIsAlternate, may be used together. It is serialized using an <tt>rdf:Alt</tt>
-    /// container. Each array element must be a simple property with an <tt>xml:lang</tt> attribute.
+    /// @param options Option flags describing the property, in which the bit-flag
+    /// \c #kXMP_PropValueIsStruct must be set to create a struct.
+
+    void SetStructField ( XMP_StringPtr   schemaNS,
+						  XMP_StringPtr   structName,
+						  XMP_StringPtr   fieldNS,
+						  XMP_StringPtr   fieldName,
+						  XMP_StringPtr   fieldValue,
+						  XMP_OptionBits  options = 0 );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief \c SetProperty is the simplest property setter, mainly for top level simple
-    /// properties or after using the path composition functions in \c TXMPUtils.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c SetStructField() creates or sets the value of a field within a nested structure,
+    /// using a string object.
     ///
-    /// \param schemaNS The namespace URI for the property. Has the same usage as in \c GetProperty.
-    ///
-    /// \param propName The name of the property. Has the same usage as in \c GetProperty.
+    /// Overloads the basic form of the function, allowing you to pass a string object in which to
+	/// return the field value. It is otherwise identical; see details in the canonical form.
+
+    void SetStructField ( XMP_StringPtr      schemaNS,
+						  XMP_StringPtr      structName,
+						  XMP_StringPtr      fieldNS,
+						  XMP_StringPtr      fieldName,
+						  const tStringObj & fieldValue,
+						  XMP_OptionBits     options = 0 );
+
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c SetQualifier() creates or sets a qualifier attached to a property.
     ///
-    /// \param propValue A pointer to the null terminated UTF-8 string that is the value of the
-    /// property, if the property has a value. Arrays and non-leaf levels of structs do not have
-    /// values. Must be null if the value is not relevant.
-    ///
-    /// \param options Option flags describing the property. See the earlier description.
-
-    void
-    SetProperty ( XMP_StringPtr  schemaNS,
-                  XMP_StringPtr  propName,
-                  XMP_StringPtr  propValue,
-                  XMP_OptionBits options = 0 );
-
-    //  --------------------------------------------------------------------------------------------
-    /// \brief This form of \c SetProperty is a simple overload in the template that calls the above
-    /// form passing <tt>propValue.c_str()</tt>.
-
-    void
-    SetProperty ( XMP_StringPtr      schemaNS,
-                  XMP_StringPtr      propName,
-                  const tStringObj & propValue,
-                  XMP_OptionBits     options = 0 );
-
-    //  --------------------------------------------------------------------------------------------
-    /// \brief \c SetArrayItem provides access to items within an array. The index is passed as an
-    /// integer, you need not worry about the path string syntax for array items, convert a loop
-    /// index to a string, etc. The array passed to \c SetArrayItem must already exist. See also
-    /// \c AppendArrayItem.
+    /// Use this to  set a value for an existing qualifier, or create a new qualifier. <<how do
+    /// options work? macro vs bit-flag? interaction w/XMP_PropHasQualifier?>> Use
+    /// \c TXMPUtils::ComposeQualifierPath() to create a complex path.
     ///
-    /// In normal usage the selected array item is modified. A new item is automatically
-    /// appended if the index is the array size plus 1. A new item may be inserted before or after
-    /// any item by using one of the following option flags:
+    /// @param schemaNS The namespace URI; see \c GetProperty().
     ///
-    /// \li \c kXMP_InsertBeforeItem - Insert a new array item before the selected one.
-    /// \li \c kXMP_InsertAfterItem -  Insert a new array item after the selected one.
+    /// @param propName The name of the property to which the qualifier is attached. Can be a
+    /// general path expression, must not be null or the empty string; see \c GetProperty() for
+    /// namespace prefix usage.
     ///
-    /// \param schemaNS The namespace URI for the array. Has the same usage as in \c GetProperty.
+    /// @param qualNS The namespace URI for the qualifier. Same namespace and prefix usage as
+    /// \c GetProperty().
     ///
-    /// \param arrayName The name of the array. May be a general path expression, must not be null
-    /// or the empty string. Has the same namespace prefix usage as \c propName in \c GetProperty.
-    ///
-    /// \param itemIndex The index of the desired item. Arrays in XMP are indexed from 1. The
-    /// constant \c kXMP_ArrayLastItem always refers to the last existing array item.
-    ///
-    /// \param itemValue A pointer to the null terminated UTF-8 string that is the value of the array
-    /// item, if the array item has a value. Has the same usage as \c propValue in \c GetProperty.
-    ///
-    /// \param options Option flags describing the item. See the earlier description.
-
-    void
-    SetArrayItem ( XMP_StringPtr  schemaNS,
-                   XMP_StringPtr  arrayName,
-                   XMP_Index      itemIndex,
-                   XMP_StringPtr  itemValue,
-                   XMP_OptionBits options = 0 );
-
-    //  --------------------------------------------------------------------------------------------
-    /// \brief This form of \c SetArrayItem is a simple overload in the template that calls the above
-    /// form passing <tt>itemValue.c_str()</tt>.
-
-    void
-    SetArrayItem ( XMP_StringPtr      schemaNS,
-                   XMP_StringPtr      arrayName,
-                   XMP_Index          itemIndex,
-                   const tStringObj & itemValue,
-                   XMP_OptionBits     options = 0 );
-
-    //  --------------------------------------------------------------------------------------------
-    /// \brief \c AppendArrayItem simplifies construction of an array by not requiring that you
-    /// pre-create an empty array. The array that is assigned is created automatically if it does
-    /// not yet exist. Each call to \c AppendArrayItem appends an item to the array. The
-    /// corresponding parameters have the same use as \c SetArrayItem. The \c arrayOptions
-    /// parameter is used to specify what kind of array. If the array exists, it must have the
-    /// specified form.
-    ///
-    /// \param schemaNS The namespace URI for the array. Has the same usage as in \c GetProperty.
+    /// @param qualName The name of the qualifier. Must be a single XML name, must not be null or
+    /// the empty string. Same namespace and prefix usage as \c GetProperty().
     ///
-    /// \param arrayName The name of the array. May be a general path expression, must not be null
-    /// or the empty string. Has the same namespace prefix usage as \c propPath in \c GetProperty.
+    /// @param qualValue The new value, a null-terminated UTF-8 string, if the qualifier has a
+    /// value. Null to create a new, empty qualifier.
     ///
-    /// \param arrayOptions Option flags describing the array form. The only valid bits are those
-    /// that are part of \c kXMP_PropArrayFormMask: \c kXMP_PropValueIsArray, \c
-    /// kXMP_PropArrayIsOrdered, \c kXMP_PropArrayIsAlternate, or \c kXMP_PropArrayIsAltText.
+    /// @param options Option flags describing the <<qualified property? qualifier?>>, a logical OR
+    /// of property-type bit-flag constants. Use the macro \c #XMP_PropIsQualifier to create a
+    /// qualifier.	 <<??>>
+
+    void SetQualifier ( XMP_StringPtr  schemaNS,
+					    XMP_StringPtr  propName,
+					    XMP_StringPtr  qualNS,
+					    XMP_StringPtr  qualName,
+					    XMP_StringPtr  qualValue,
+					    XMP_OptionBits options = 0 );
+
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c SetQualifier() creates or sets a qualifier attached to a property using a string object.
     ///
-    /// \param itemValue A pointer to the null terminated UTF-8 string that is the value of the
-    /// array item, if the array item has a value. Has the same usage as \c propValue in \c
-    /// GetProperty.
-    ///
-    /// \param itemOptions Option flags describing the item. See the earlier description.
-
-    void
-    AppendArrayItem ( XMP_StringPtr  schemaNS,
-                      XMP_StringPtr  arrayName,
-                      XMP_OptionBits arrayOptions,
-                      XMP_StringPtr  itemValue,
-                      XMP_OptionBits itemOptions = 0 );
-
-    //  --------------------------------------------------------------------------------------------
-    /// \brief This form of \c AppendArrayItem is a simple overload in the template that calls the
-    /// above form passing <tt>itemValue.c_str()</tt>.
-
-    void
-    AppendArrayItem ( XMP_StringPtr      schemaNS,
-                      XMP_StringPtr      arrayName,
-                      XMP_OptionBits     arrayOptions,
-                      const tStringObj & itemValue,
-                      XMP_OptionBits     itemOptions = 0 );
-
-    //  --------------------------------------------------------------------------------------------
-    /// \brief \c SetStructField provides access to fields within a nested structure. The namespace
-    /// for the field is passed as a URI, you need not worry about the path string syntax.
-    ///
-    /// The names of fields should be XML qualified names, that is within an XML namespace. The
-    /// path syntax for a qualified name uses the namespace prefix, which is unreliable because
-    /// the prefix is never guaranteed. The URI is the formal name, the prefix is just a local
-    /// shorthand in a given sequence of XML text.
-    ///
-    /// \param schemaNS The namespace URI for the struct. Has the same usage as in \c GetProperty.
-    ///
-    /// \param structName The name of the struct. May be a general path expression, must not be
-    /// null or the empty string. Has the same namespace prefix usage as \c propName in \c
-    /// GetProperty.
-    ///
-    /// \param fieldNS The namespace URI for the field. Has the same URI and prefix usage as the \c
-    /// schemaNS parameter.
-    ///
-    /// \param fieldName The name of the field. Must be a single XML name, must not be null or the
-    /// empty string. Has the same namespace prefix usage as the \c structName parameter.
-    ///
-    /// \param fieldValue A pointer to the null terminated UTF-8 string that is the value of the
-    /// field, if the field has a value. Has the same usage as \c propValue in \c GetProperty.
-    ///
-    /// \param options Option flags describing the field. See the earlier description.
-
-    void
-    SetStructField ( XMP_StringPtr   schemaNS,
-                     XMP_StringPtr   structName,
-                     XMP_StringPtr   fieldNS,
-                     XMP_StringPtr   fieldName,
-                     XMP_StringPtr   fieldValue,
-                     XMP_OptionBits  options = 0 );
-
-    //  --------------------------------------------------------------------------------------------
-    /// \brief This form of \c SetStructField is a simple overload in the template that calls the
-    /// above form passing <tt>fieldValue.c_str()</tt>.
-
-    void
-    SetStructField ( XMP_StringPtr      schemaNS,
-                     XMP_StringPtr      structName,
-                     XMP_StringPtr      fieldNS,
-                     XMP_StringPtr      fieldName,
-                     const tStringObj & fieldValue,
-                     XMP_OptionBits     options = 0 );
-
-    //  --------------------------------------------------------------------------------------------
-    /// \brief \c SetQualifier provides access to a qualifier attached to a property. The namespace
-    /// for the qualifier is passed as a URI, you need not worry about the path string syntax. In
-    /// many regards qualifiers are like struct fields. See the introductory discussion of
-    /// qualified properties for more information.
-    ///
-    /// The names of qualifiers should be XML qualified names, that is within an XML namespace. The
-    /// path syntax for a qualified name uses the namespace prefix, which is unreliable because
-    /// the prefix is never guaranteed. The URI is the formal name, the prefix is just a local
-    /// shorthand in a given sequence of XML text.
-    ///
-    /// \param schemaNS The namespace URI for the struct. Has the same usage as in \c GetProperty.
-    ///
-    /// \param propName The name of the property to which the qualifier is attached. Has the same
-    /// usage as in \c GetProperty.
-    ///
-    /// \param qualNS The namespace URI for the qualifier. Has the same URI and prefix usage as the
-    /// \c schemaNS parameter.
-    ///
-    /// \param qualName The name of the qualifier. Must be a single XML name, must not be null or
-    /// the empty string. Has the same namespace prefix usage as the \c propName parameter.
-    ///
-    /// \param qualValue A pointer to the null terminated UTF-8 string that is the value of the
-    /// qualifier, if the qualifier has a value. Has the same usage as \c propValue in \c
-    /// GetProperty.
-    ///
-    /// \param options Option flags describing the qualifier. See the earlier description.
-
-    void
-    SetQualifier ( XMP_StringPtr  schemaNS,
-                   XMP_StringPtr  propName,
-                   XMP_StringPtr  qualNS,
-                   XMP_StringPtr  qualName,
-                   XMP_StringPtr  qualValue,
-                   XMP_OptionBits options = 0 );
-
-    //  --------------------------------------------------------------------------------------------
-    /// \brief This form of \c SetQualifier is a simple overload in the template that calls the above
-    /// form passing <tt>qualValue.c_str()</tt>.
-
-    void
-    SetQualifier ( XMP_StringPtr      schemaNS,
-                   XMP_StringPtr      propName,
-                   XMP_StringPtr      qualNS,
-                   XMP_StringPtr      qualName,
-                   const tStringObj & qualValue,
-                   XMP_OptionBits     options = 0 );
+    /// Overloads the basic form of the function, allowing you to pass a string object
+	/// for the qualifier value. It is otherwise identical; see details in the canonical form.
+
+    void SetQualifier ( XMP_StringPtr      schemaNS,
+					    XMP_StringPtr      propName,
+					    XMP_StringPtr      qualNS,
+					    XMP_StringPtr      qualName,
+					    const tStringObj & qualValue,
+					    XMP_OptionBits     options = 0 );
 
     /// @}
 
     // =============================================================================================
 
-    //  --------------------------------------------------------------------------------------------
-    /// \name Functions for deleting and detecting properties.
+    // ---------------------------------------------------------------------------------------------
+    /// \name Detecting and deleting properties.
     /// @{
-    /// These should be obvious from the descriptions of the getters and setters.
+    ///
+    /// The namespace URI and prefix usage for property specifiers in these functions is the same as
+    /// for \c TXMPMeta::GetProperty().
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief \c DeleteProperty deletes the given XMP subtree rooted at the given property. It is
-    /// not an error if the property does not exist.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c DeleteProperty() deletes an XMP subtree rooted at a given property.
     ///
-    /// \param schemaNS The namespace URI for the property. Has the same usage as in \c GetProperty.
+    /// It is not an error if the property does not exist.
     ///
-    /// \param propName The name of the property. Has the same usage as in \c GetProperty.
+    /// @param schemaNS The namespace URI for the property; see \c GetProperty().
+    ///
+    /// @param propName The name of the property; see \c GetProperty().
 
-    void
-    DeleteProperty ( XMP_StringPtr schemaNS,
-                     XMP_StringPtr propName );
+    void DeleteProperty ( XMP_StringPtr schemaNS,
+                     	  XMP_StringPtr propName );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief \c DeleteArrayItem deletes the given XMP subtree rooted at the given array item. It
-    /// is not an error if the array item does not exist.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c DeleteArrayItem() deletes an XMP subtree rooted at a given array item.
+    ///
+    /// It is not an error if the array item does not exist. Use
+    /// \c TXMPUtils::ComposeArrayItemPath() to create a complex path.
     ///
-    /// \param schemaNS The namespace URI for the array. Has the same usage as in \c GetProperty.
+    /// @param schemaNS The namespace URI for the array; see \c GetProperty().
     ///
-    /// \param arrayName The name of the array. May be a general path expression, must not be null
-    /// or the empty string. Has the same namespace prefix usage as \c propName in \c GetProperty.
+    /// @param arrayName The name of the array. Can be a general path expression, must not be null
+    /// or the empty string; see \c GetProperty() for namespace prefix usage.
     ///
-    /// \param itemIndex The index of the desired item. Arrays in XMP are indexed from 1. The
-    /// constant \c kXMP_ArrayLastItem always refers to the last existing array item.
+    /// @param itemIndex The 1-based index of the desired item. Use the macro \c #kXMP_ArrayLastItem
+    /// to specify the last existing array item.
 
-    void
-    DeleteArrayItem ( XMP_StringPtr schemaNS,
-                      XMP_StringPtr arrayName,
-                      XMP_Index     itemIndex );
+    void DeleteArrayItem ( XMP_StringPtr schemaNS,
+						   XMP_StringPtr arrayName,
+						   XMP_Index     itemIndex );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief \c DeleteStructField deletes the given XMP subtree rooted at the given struct field.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c DeleteStructField() deletes an XMP subtree rooted at a given struct field.
+    ///
     /// It is not an error if the field does not exist.
     ///
-    /// \param schemaNS The namespace URI for the struct. Has the same usage as in \c GetProperty.
+    /// @param schemaNS The namespace URI for the struct; see \c GetProperty().
     ///
-    /// \param structName The name of the struct. May be a general path expression, must not be null
-    /// or the empty string. Has the same namespace prefix usage as \c propName in \c GetProperty.
+    /// @param structName The name of the struct. Can be a general path expression, must not be null
+    /// or the empty string; see \c GetProperty() for namespace prefix usage.
     ///
-    /// \param fieldNS The namespace URI for the field. Has the same URI and prefix usage as the
-    /// \c schemaNS parameter.
+    /// @param fieldNS The namespace URI for the field. Same namespace and prefix usage as
+    /// \c GetProperty().
     ///
-    /// \param fieldName The name of the field. Must be a single XML name, must not be null or the
-    /// empty string. Has the same namespace prefix usage as the \c structName parameter.
+    /// @param fieldName The name of the field. Must be a single XML name, must not be null or the
+    /// empty string. Same namespace and prefix usage as \c GetProperty().
 
-    void
-    DeleteStructField ( XMP_StringPtr schemaNS,
-                        XMP_StringPtr structName,
-                        XMP_StringPtr fieldNS,
-                        XMP_StringPtr fieldName );
+    void DeleteStructField ( XMP_StringPtr schemaNS,
+							 XMP_StringPtr structName,
+							 XMP_StringPtr fieldNS,
+							 XMP_StringPtr fieldName );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief \c DeleteQualifier deletes the given XMP subtree rooted at the given qualifier. It
-    /// is not an error if the qualifier does not exist.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c DeleteQualifier() deletes an XMP subtree rooted at a given qualifier.
+    ///
+    /// It is not an error if the qualifier does not exist.
     ///
-    /// \param schemaNS The namespace URI for the struct. Has the same usage as in \c GetProperty.
+    /// @param schemaNS The namespace URI; see \c GetProperty().
     ///
-    /// \param propName The name of the property to which the qualifier is attached. Has the same
-    /// usage as in \c GetProperty.
+    /// @param propName The name of the property to which the qualifier is attached. Can be a
+    /// general path expression, must not be null or the empty string; see \c GetProperty() for
+    /// namespace prefix usage.
     ///
-    /// \param qualNS The namespace URI for the qualifier. Has the same URI and prefix usage as the
-    /// \c schemaNS parameter.
+    /// @param qualNS The namespace URI for the qualifier. Same namespace and prefix usage as
+    /// \c GetProperty().
     ///
-    /// \param qualName The name of the qualifier. Must be a single XML name, must not be null or the
-    /// empty string. Has the same namespace prefix usage as the \c propName parameter.
+    /// @param qualName The name of the qualifier. Must be a single XML name, must not be null or
+    /// the empty string. Same namespace and prefix usage as \c GetProperty().
 
-    void
-    DeleteQualifier ( XMP_StringPtr schemaNS,
-                      XMP_StringPtr propName,
-                      XMP_StringPtr qualNS,
-                      XMP_StringPtr qualName );
+    void DeleteQualifier ( XMP_StringPtr schemaNS,
+						   XMP_StringPtr propName,
+						   XMP_StringPtr qualNS,
+						   XMP_StringPtr qualName );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief \c DoesPropertyExist tells if the property exists.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c DoesPropertyExist() reports whether a property currently exists.
     ///
-    /// \result Returns true if the property exists.
+    /// @param schemaNS The namespace URI for the property; see \c GetProperty().
     ///
-    /// \param schemaNS The namespace URI for the property. Has the same usage as in \c GetProperty.
+    /// @param propName The name of the property; see \c GetProperty().
     ///
-    /// \param propName The name of the property. Has the same usage as in \c GetProperty.
+    /// @return True if the property exists.
 
-    bool
-    DoesPropertyExist ( XMP_StringPtr schemaNS,
-                        XMP_StringPtr propName ) const;
+    bool DoesPropertyExist ( XMP_StringPtr schemaNS,
+                        	 XMP_StringPtr propName ) const;
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief \c DoesArrayItemExist tells if the array item exists.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c DoesArrayItemExist() reports whether an array item currently exists.
     ///
-    /// \result Returns true if the array item exists.
+    /// Use \c TXMPUtils::ComposeArrayItemPath() to create a complex path.
     ///
-    /// \param schemaNS The namespace URI for the array. Has the same usage as in \c GetProperty.
+    /// @param schemaNS The namespace URI; see \c GetProperty().
     ///
-    /// \param arrayName The name of the array. May be a general path expression, must not be null
-    /// or the empty string. Has the same namespace prefix usage as \c propName in \c GetProperty.
+    /// @param arrayName The name of the array. Can be a general path expression, must not be null
+    /// or the empty string; see \c GetProperty() for namespace prefix usage.
     ///
-    /// \param itemIndex The index of the desired item. Arrays in XMP are indexed from 1. The
-    /// constant \c kXMP_ArrayLastItem always refers to the last existing array item.
+    /// @param itemIndex The 1-based index of the desired item. Use the macro \c #kXMP_ArrayLastItem
+    /// to specify the last existing array item.
+    ///
+    /// @return True if the array item exists.
 
-    bool
-    DoesArrayItemExist ( XMP_StringPtr schemaNS,
-                         XMP_StringPtr arrayName,
-                         XMP_Index     itemIndex ) const;
+    bool DoesArrayItemExist ( XMP_StringPtr schemaNS,
+							  XMP_StringPtr arrayName,
+							  XMP_Index     itemIndex ) const;
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief \c DoesStructFieldExist tells if the struct field exists.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c DoesStructFieldExist() reports whether a struct field currently exists.
+    ///
+    /// Use \c TXMPUtils::ComposeStructFieldPath() to create a complex path.
     ///
-    /// \result Returns true if the field exists.
+    /// @param schemaNS The namespace URI; see \c GetProperty().
     ///
-    /// \param schemaNS The namespace URI for the struct. Has the same usage as in \c GetProperty.
+    /// @param structName The name of the struct. Can be a general path expression, must not be null
+    /// or the empty string; see \c GetProperty() for namespace prefix usage.
     ///
-    /// \param structName The name of the struct. May be a general path expression, must not be null
-    /// or the empty string. Has the same namespace prefix usage as \c propName in \c GetProperty.
+    /// @param fieldNS The namespace URI for the field. Same namespace and prefix usage as
+    /// \c GetProperty().
     ///
-    /// \param fieldNS The namespace URI for the field. Has the same URI and prefix usage as the
-    /// \c schemaNS parameter.
+    /// @param fieldName The name of the field. Must be a single XML name, must not be null or the
+    /// empty string. Same namespace and prefix usage as \c GetProperty().
     ///
-    /// \param fieldName The name of the field. Must be a single XML name, must not be null or the
-    /// empty string. Has the same namespace prefix usage as the \c structName parameter.
+    /// @return True if the field exists.
 
-    bool
-    DoesStructFieldExist ( XMP_StringPtr schemaNS,
-                           XMP_StringPtr structName,
-                           XMP_StringPtr fieldNS,
-                           XMP_StringPtr fieldName ) const;
+    bool DoesStructFieldExist ( XMP_StringPtr schemaNS,
+							    XMP_StringPtr structName,
+							    XMP_StringPtr fieldNS,
+							    XMP_StringPtr fieldName ) const;
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief  \c DoesQualifierExist tells if the qualifier exists.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c DoesQualifierExist() reports whether a qualifier currently exists.
     ///
-    /// \result Returns true if the qualifier exists.
+    /// @param schemaNS The namespace URI; see \c GetProperty().
     ///
-    /// \param schemaNS The namespace URI for the struct. Has the same usage as in \c GetProperty.
+    /// @param propName The name of the property to which the qualifier is attached. Can be a
+    /// general path expression, must not be null or the empty string; see \c GetProperty() for
+    /// namespace prefix usage.
     ///
-    /// \param propName The name of the property to which the qualifier is attached. Has the same
-    /// usage as in \c GetProperty.
+    /// @param qualNS The namespace URI for the qualifier. Same namespace and prefix usage as
+    /// \c GetProperty().
     ///
-    /// \param qualNS The namespace URI for the qualifier. Has the same URI and prefix usage as the
-    /// \c schemaNS parameter.
+    /// @param qualName The name of the qualifier. Must be a single XML name, must not be null or
+    /// the empty string. Same namespace and prefix usage as \c GetProperty().
     ///
-    /// \param qualName The name of the qualifier. Must be a single XML name, must not be null or the
-    /// empty string. Has the same namespace prefix usage as the \c propName parameter.
+    /// @return True if the qualifier exists.
 
-    bool
-    DoesQualifierExist ( XMP_StringPtr schemaNS,
-                         XMP_StringPtr propName,
-                         XMP_StringPtr qualNS,
-                         XMP_StringPtr qualName ) const;
+    bool DoesQualifierExist ( XMP_StringPtr schemaNS,
+							  XMP_StringPtr propName,
+							  XMP_StringPtr qualNS,
+							  XMP_StringPtr qualName ) const;
 
     /// @}
 
     // =============================================================================================
     // Specialized Get and Set functions
-    // =================================
+    // =============================================================================================
 
-    //  --------------------------------------------------------------------------------------------
-    /// \name Functions for accessing localized text (alt-text) properties.
+    // ---------------------------------------------------------------------------------------------
+    /// \name Accessing properties as binary values.
     /// @{
-    /// These functions provide convenient support for localized text properties, including a number
-    /// of special and obscure aspects. Localized text properties are stored in alt-text arrays.
-    /// They allow multiple concurrent localizations of a property value, for example a document
-    /// title or copyright in several languages.
-    ///
-    /// The most important aspect of these functions is that they select an appropriate array item
-    /// based on one or two RFC 3066 language tags. One of these languages, the "specific" language,
-    /// is preferred and selected if there is an exact match. For many languages it is also possible
-    /// to define a "generic" language that may be used if there is no specific language match. The
-    /// generic language must be a valid RFC 3066 primary subtag, or the empty string.
-    ///
-    /// For example, a specific language of "en-US" should be used in the US, and a specific language
-    /// of "en-UK" should be used in England. It is also appropriate to use "en" as the generic
-    /// language in each case. If a US document goes to England, the "en-US" title is selected
-    /// by using the "en" generic language and the "en-UK" specific language.
-    ///
-    ///	It is considered poor practice, but allowed, to pass a specific language that is just an
-    /// RFC 3066 primary tag. For example "en" is not a good specific language, it should only be
-    /// used as a generic language. Passing "i" or "x" as the generic language is also considered
-    /// poor practice but allowed.
-    ///
-    /// Advice from the W3C about the use of RFC 3066 language tags can be found at:
-    /// \li http://www.w3.org/International/articles/language-tags/
     ///
-    /// \note RFC 3066 language tags must be treated in a case insensitive manner. The XMP toolkit
-    /// does this by normalizing their capitalization:
+	/// These are very similar to \c TXMPMeta::GetProperty() and \c TXMPMeta::SetProperty(), except
+	/// that the value is returned or provided in binary form instead of as a UTF-8 string.
+	/// \c TXMPUtils provides functions for converting between binary and string values.
+    /// Use the path composition functions in  \c TXMPUtils	to compose complex path expressions
+    /// for fields or items in nested structures or arrays, or for qualifiers.
+
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c GetProperty_Bool() retrieves the value of a Boolean property as a C++ bool.
     ///
-	/// \li The primary subtag is lower case, the suggested practice of ISO 639.
-	/// \li All 2 letter secondary subtags are upper case, the suggested practice of ISO 3166.
-	/// \li All other subtags are lower case.
+    /// Reports whether a property exists, and retrieves its binary value and property type information.
     ///
-    /// The XMP specification defines an artificial language, "x-default", that is used to
-    /// explicitly denote a default item in an alt-text array. The XMP toolkit normalizes alt-text
-    /// arrays such that the x-default item is the first item. The \c SetLocalizedText function has
-    /// several special features related to the x-default item, see its description for details.
+    /// @param schemaNS The namespace URI; see \c GetProperty().
     ///
-    /// The selection of the array item is the same for \c GetLocalizedText and \c SetLocalizedText:
+    /// @param propName The name of the property. Can be a general path expression, must not be null
+    /// or the empty string; see \c GetProperty() for namespace prefix usage.
     ///
-    /// \li Look for an exact match with the specific language.
-    /// \li If a generic language is given, look for a partial match.
-    /// \li Look for an x-default item.
-    /// \li Choose the first item.
+    /// @param propValue [out] A buffer in which to return the binary value. Can be null if the
+    /// value is not wanted. Must be null for arrays and non-leaf levels of structs that do not have
+    /// values.
     ///
-    /// A partial match with the generic language is where the start of the item's language matches
-    /// the generic string and the next character is '-'. An exact match is also recognized as a
-    /// degenerate case.
+    /// @param options [out] A buffer in which to return the option flags describing the property, a
+    /// logical OR of allowed bit-flag constants; see \c #kXMP_PropValueIsStruct and following. Can
+    /// be null if flags are not wanted.
     ///
-    /// It is fine to pass x-default as the specific language. In this case, selection of an x-default
-    /// item is an exact match by the first rule, not a selection by the 3rd rule. The last 2 rules
-    /// are fallbacks used when the specific and generic languages fail to produce a match.
+    /// @return True if the property exists.
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief \c GetLocalizedText returns information about a selected item in an alt-text array.
-    /// The array item is selected according to the rules given above.
-    ///
-    /// \result Returns true if an appropriate array item exists.
-    ///
-    /// \param schemaNS The namespace URI for the alt-text array. Has the same usage as in \c
-    /// GetProperty.
+    bool GetProperty_Bool ( XMP_StringPtr    schemaNS,
+						    XMP_StringPtr    propName,
+						    bool *           propValue,
+						    XMP_OptionBits * options ) const;
+
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c GetProperty_Int() retrieves the value of an integer property as a C long integer.
     ///
-    /// \param altTextName The name of the alt-text array. May be a general path expression, must
-    /// not be null or the empty string. Has the same namespace prefix usage as \c propName in \c
-    /// GetProperty.
+    /// Reports whether a property exists, and retrieves its binary value and property type information.
     ///
-    /// \param genericLang The name of the generic language as an RFC 3066 primary subtag. May be
-    /// null or the empty string if no generic language is wanted.
+    /// @param schemaNS The namespace URI; see \c GetProperty().
     ///
-    /// \param specificLang The name of the specific language as an RFC 3066 tag. Must not be null
-    /// or the empty string.
+    /// @param propName The name of the property. Can be a general path expression, must not be null
+    /// or the empty string; see \c GetProperty() for namespace prefix usage.
     ///
-    /// \param actualLang A pointer to the string that is assigned the language of the selected
-    /// array item, if an appropriate array item is found. May be null if the language is not
-    /// wanted.
+    /// @param propValue [out] A buffer in which to return the binary value. Can be null if the
+    /// value is not wanted. Must be null for arrays and non-leaf levels of structs that do not have
+    /// values.
     ///
-    /// \param itemValue A pointer to the string that is assigned the value of the array item, if
-    /// an appropriate array item is found. May be null if the value is not wanted.
+    /// @param options [out] A buffer in which to return the option flags describing the property, a
+    /// logical OR of allowed bit-flag constants; see \c #kXMP_PropValueIsStruct and following. Can
+    /// be null if flags are not wanted.
     ///
-    /// \param options A pointer to the \c XMP_OptionBits variable that is assigned option flags
-    /// describing the array item. May be null if the flags are not wanted.
+    /// @return True if the property exists.
 
-    bool
-    GetLocalizedText ( XMP_StringPtr    schemaNS,
-                       XMP_StringPtr    altTextName,
-                       XMP_StringPtr    genericLang,
-                       XMP_StringPtr    specificLang,
-                       tStringObj *     actualLang,
-                       tStringObj *     itemValue,
-                       XMP_OptionBits * options ) const;
+    bool GetProperty_Int ( XMP_StringPtr    schemaNS,
+						   XMP_StringPtr    propName,
+						   long *           propValue,
+						   XMP_OptionBits * options ) const;
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief \c SetLocalizedText modifies the value of a selected item in an alt-text array.
-    /// Creates an appropriate array item if necessary, and handles special cases for the x-default
-    /// item.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c GetProperty_Int64() retrieves the value of an integer property as a C long long integer.
     ///
-    /// If the selected item is from a match with the specific language, the value of that item is
-    /// modified. If the existing value of that item matches the existing value of the x-default
-    /// item, the x-default item is also modified. If the array only has 1 existing item (which is
-    /// not x-default), an x-default item is added with the given value.
+    /// Reports whether a property exists, and retrieves its binary value and property type information.
     ///
-    /// If the selected item is from a match with the generic language and there are no other
-    /// generic matches, the value of that item is modified. If the existing value of that item
-    /// matches the existing value of the x-default item, the x-default item is also modified. If
-    /// the array only has 1 existing item (which is not x-default), an x-default item is added
-    /// with the given value.
+    /// @param schemaNS The namespace URI; see \c GetProperty().
     ///
-    /// If the selected item is from a partial match with the generic language and there are other
-    /// partial matches, a new item is created for the specific language. The x-default item is not
-    /// modified.
+    /// @param propName The name of the property. Can be a general path expression, must not be null
+    /// or the empty string; see \c GetProperty() for namespace prefix usage.
     ///
-    /// If the selected item is from the last 2 rules then a new item is created for the specific
-    /// language. If the array only had an x-default item, the x-default item is also modified. If
-    /// the array was empty, items are created for the specific language and x-default.
+    /// @param propValue [out] A buffer in which to return the binary value. Can be null if the
+    /// value is not wanted. Must be null for arrays and non-leaf levels of structs that do not have
+    /// values.
     ///
-    /// \param schemaNS The namespace URI for the alt-text array. Has the same usage as in \c
-    /// GetProperty.
+    /// @param options [out] A buffer in which to return the option flags describing the property, a
+    /// logical OR of allowed bit-flag constants; see \c #kXMP_PropValueIsStruct and following. Can
+    /// be null if flags are not wanted.
     ///
-    /// \param altTextName The name of the alt-text array. May be a general path expression, must
-    /// not be null or the empty string. Has the same namespace prefix usage as \c propName in \c
-    /// GetProperty.
+    /// @return True if the property exists.
+
+    bool GetProperty_Int64 ( XMP_StringPtr    schemaNS,
+							 XMP_StringPtr    propName,
+							 long long *      propValue,
+							 XMP_OptionBits * options ) const;
+
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c GetProperty_Float() retrieves the value of a floating-point property as a C double float.
     ///
-    /// \param genericLang The name of the generic language as an RFC 3066 primary subtag. May be
-    /// null or the empty string if no generic language is wanted.
+    /// Reports whether a property exists, and retrieves its binary value and property type information.
     ///
-    /// \param specificLang The name of the specific language as an RFC 3066 tag. Must not be null
-    /// or the empty string.
+    /// @param schemaNS The namespace URI; see \c GetProperty().
     ///
-    /// \param itemValue A pointer to the null terminated UTF-8 string that is the new value for
-    /// the appropriate array item.
+    /// @param propName The name of the property. Can be a general path expression, must not be null
+    /// or the empty string; see \c GetProperty() for namespace prefix usage.
     ///
-    /// \param options Option flags, none are defined at present.
-
-    void
-    SetLocalizedText ( XMP_StringPtr  schemaNS,
-                       XMP_StringPtr  altTextName,
-                       XMP_StringPtr  genericLang,
-                       XMP_StringPtr  specificLang,
-                       XMP_StringPtr  itemValue,
-                       XMP_OptionBits options = 0 );
-
-    //  --------------------------------------------------------------------------------------------
-    /// \brief This form of \c SetLocalizedText is a simple overload in the template that calls the
-    /// above form passing <tt>itemValue.c_str()</tt>.
-
-    void
-    SetLocalizedText ( XMP_StringPtr      schemaNS,
-                       XMP_StringPtr      altTextName,
-                       XMP_StringPtr      genericLang,
-                       XMP_StringPtr      specificLang,
-                       const tStringObj & itemValue,
-                       XMP_OptionBits     options = 0 );
-
-    /// @}
-
-    // =============================================================================================
+    /// @param propValue [out] A buffer in which to return the binary value. Can be null if the
+    /// value is not wanted. Must be null for arrays and non-leaf levels of structs that do not have
+    /// values.
+    ///
+    /// @param options [out] A buffer in which to return the option flags describing the property, a
+    /// logical OR of allowed bit-flag constants; see \c #kXMP_PropValueIsStruct and following. Can
+    /// be null if flags are not wanted.
+    ///
+    /// @return True if the property exists.
 
-    //  --------------------------------------------------------------------------------------------
-    /// \name Functions accessing properties as binary values.
-    /// @{
-	/// These are very similar to \c GetProperty and \c SetProperty above, but the value is
-	/// returned or
-    /// provided in binary form instead of as a UTF-8 string. The path composition functions in
-    /// \c TXMPUtils may be used to compose an path expression for fields in nested structures, items
-    /// in arrays, or qualifiers.
+    bool GetProperty_Float ( XMP_StringPtr    schemaNS,
+							 XMP_StringPtr    propName,
+							 double *         propValue,
+							 XMP_OptionBits * options ) const;
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief \c GetProperty_Bool returns the value of a Boolean property as a C++ bool.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c GetProperty_Date() retrieves the value of a date-time property as an \c #XMP_DateTime structure.
     ///
-    /// \result Returns true if the property exists.
+    /// Reports whether a property exists, and retrieves its binary value and property type information.
     ///
-    /// \param schemaNS The namespace URI for the property. Has the same usage as in \c GetProperty.
+    /// @param schemaNS The namespace URI; see \c GetProperty().
     ///
-    /// \param propName The name of the property. Has the same usage as in \c GetProperty.
+    /// @param propName The name of the property. Can be a general path expression, must not be null
+    /// or the empty string; see \c GetProperty() for namespace prefix usage.
     ///
-    /// \param propValue A pointer to the bool variable that is assigned the value of the property.
-    /// May be null if the value is not wanted.
+    /// @param propValue [out] A buffer in which to return the binary value. Can be null if the
+    /// value is not wanted. Must be null for arrays and non-leaf levels of structs that do not have
+    /// values.
     ///
-    /// \param options A pointer to the \c XMP_OptionBits variable that is assigned option flags
-    /// describing the property. May be null if the flags are not wanted.
+    /// @param options [out] A buffer in which to return the option flags describing the property, a
+    /// logical OR of allowed bit-flag constants; see \c #kXMP_PropValueIsStruct and following. Can
+    /// be null if flags are not wanted.
+    ///
+    /// @return True if the property exists.
 
-    bool
-    GetProperty_Bool ( XMP_StringPtr    schemaNS,
-                       XMP_StringPtr    propName,
-                       bool *           propValue,
-                       XMP_OptionBits * options ) const;
+    bool GetProperty_Date ( XMP_StringPtr    schemaNS,
+						    XMP_StringPtr    propName,
+						    XMP_DateTime *   propValue,
+						    XMP_OptionBits * options ) const;
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief \c GetProperty_Int returns the value of an integer property as a C long integer.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c SetProperty_Bool() sets the value of a Boolean property using a C++ bool.
     ///
-    /// \result Returns true if the property exists.
+    /// Sets a property with a binary value, creating it if necessary.
     ///
-    /// \param schemaNS The namespace URI for the property. Has the same usage as in \c GetProperty.
+    /// @param schemaNS The namespace URI; see \c GetProperty().
     ///
-    /// \param propName The name of the property. Has the same usage as in \c GetProperty.
+    /// @param propName The name of the property. Can be a general path expression, must not be null
+    /// or the empty string; see \c GetProperty() for namespace prefix usage.
     ///
-    /// \param propValue A pointer to the long integer variable that is assigned the value of
-    /// the property. May be null if the value is not wanted.
+    /// @param propValue The new binary value. Can be null if creating the property. Must be null
+    /// for arrays and non-leaf levels of structs that do not have values.
     ///
-    /// \param options A pointer to the \c XMP_OptionBits variable that is assigned option flags
-    /// describing the property. May be null if the flags are not wanted.
+    /// @param options Option flags describing the property; a logical OR of allowed bit-flag
+    /// constants; see \c #kXMP_PropValueIsStruct and following. Must match the type of a property
+    /// that already exists.
 
-    bool
-    GetProperty_Int ( XMP_StringPtr    schemaNS,
-                      XMP_StringPtr    propName,
-                      long *           propValue,
-                      XMP_OptionBits * options ) const;
+    void SetProperty_Bool ( XMP_StringPtr  schemaNS,
+						    XMP_StringPtr  propName,
+						    bool           propValue,
+						    XMP_OptionBits options = 0 );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief \c GetProperty_Int64 returns the value of an integer property as a C long long integer.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c SetProperty_Int() sets the value of an integer property using a C long integer.
     ///
-    /// \result Returns true if the property exists.
+    /// Sets a property with a binary value, creating it if necessary.
     ///
-    /// \param schemaNS The namespace URI for the property. Has the same usage as in \c GetProperty.
+    /// @param schemaNS The namespace URI; see \c GetProperty().
     ///
-    /// \param propName The name of the property. Has the same usage as in \c GetProperty.
+    /// @param propName The name of the property. Can be a general path expression, must not be null
+    /// or the empty string; see \c GetProperty() for namespace prefix usage.
     ///
-    /// \param propValue A pointer to the long long integer variable that is assigned the value of
-    /// the property. May be null if the value is not wanted.
+    /// @param propValue The new binary value. Can be null if creating the property. Must be null
+    /// for arrays and non-leaf levels of structs that do not have values.
     ///
-    /// \param options A pointer to the \c XMP_OptionBits variable that is assigned option flags
-    /// describing the property. May be null if the flags are not wanted.
+    /// @param options Option flags describing the property; a logical OR of allowed bit-flag
+    /// constants; see \c #kXMP_PropValueIsStruct and following. Must match the type of a property
+    /// that already exists.
 
-    bool
-    GetProperty_Int64 ( XMP_StringPtr    schemaNS,
-                        XMP_StringPtr    propName,
-                        long long *      propValue,
-                        XMP_OptionBits * options ) const;
+    void SetProperty_Int ( XMP_StringPtr  schemaNS,
+						   XMP_StringPtr  propName,
+						   long           propValue,
+						   XMP_OptionBits options = 0 );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief \c GetProperty_Float returns the value of a flaoting point property as a C double float.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c SetProperty_Int64() sets the value of an integer property using a C long long integer.
     ///
-    /// \result Returns true if the property exists.
+    /// Sets a property with a binary value, creating it if necessary.
     ///
-    /// \param schemaNS The namespace URI for the property. Has the same usage as in \c GetProperty.
+    /// @param schemaNS The namespace URI; see \c GetProperty().
     ///
-    /// \param propName The name of the property. Has the same usage as in \c GetProperty.
+    /// @param propName The name of the property. Can be a general path expression, must not be null
+    /// or the empty string; see \c GetProperty() for namespace prefix usage.
     ///
-    /// \param propValue A pointer to the double float variable that is assigned the value of
-    /// the property. May be null if the value is not wanted.
+    /// @param propValue The new binary value. Can be null if creating the property. Must be null
+    /// for arrays and non-leaf levels of structs that do not have values.
     ///
-    /// \param options A pointer to the \c XMP_OptionBits variable that is assigned option flags
-    /// describing the property. May be null if the flags are not wanted.
+    /// @param options Option flags describing the property; a logical OR of allowed bit-flag
+    /// constants; see \c #kXMP_PropValueIsStruct and following. Must match the type of a property
+    /// that already exists.
 
-    bool
-    GetProperty_Float ( XMP_StringPtr    schemaNS,
-                        XMP_StringPtr    propName,
-                        double *         propValue,
-                        XMP_OptionBits * options ) const;
+    void SetProperty_Int64 ( XMP_StringPtr  schemaNS,
+							 XMP_StringPtr  propName,
+							 long long      propValue,
+							 XMP_OptionBits options = 0 );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief \c GetProperty_Date returns the value of a date/time property as an \c XMP_DateTime struct.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c SetProperty_Float() sets the value of a floating-point property using a C double float.
     ///
-    /// \result Returns true if the property exists.
+    /// Sets a property with a binary value, creating it if necessary.
     ///
-    /// \param schemaNS The namespace URI for the property. Has the same usage as in \c GetProperty.
+    /// @param schemaNS The namespace URI; see \c GetProperty().
     ///
-    /// \param propName The name of the property. Has the same usage as in \c GetProperty.
+    /// @param propName The name of the property. Can be a general path expression, must not be null
+    /// or the empty string; see \c GetProperty() for namespace prefix usage.
     ///
-    /// \param propValue A pointer to the \c XMP_DateTime variable that is assigned the value of
-    /// the property. May be null if the value is not wanted.
+    /// @param propValue The new binary value. Can be null if creating the property. Must be null
+    /// for arrays and non-leaf levels of structs that do not have values.
     ///
-    /// \param options A pointer to the \c XMP_OptionBits variable that is assigned option flags
-    /// describing the property. May be null if the flags are not wanted.
+    /// @param options Option flags describing the property; a logical OR of allowed bit-flag
+    /// constants; see \c #kXMP_PropValueIsStruct and following. Must match the type of a property
+    /// that already exists.
 
-    bool
-    GetProperty_Date ( XMP_StringPtr    schemaNS,
-                       XMP_StringPtr    propName,
-                       XMP_DateTime *   propValue,
-                       XMP_OptionBits * options ) const;
+    void SetProperty_Float ( XMP_StringPtr  schemaNS,
+							 XMP_StringPtr  propName,
+							 double         propValue,
+							 XMP_OptionBits options = 0 );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief \c SetProperty_Bool sets the value of a Boolean property from a C++ bool.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c SetProperty_Date() sets the value of a date/time property using an \c #XMP_DateTime structure.
+    ///
+    /// Sets a property with a binary value, creating it if necessary.
     ///
-    /// \param schemaNS The namespace URI for the property. Has the same usage as in \c GetProperty.
+    /// @param schemaNS The namespace URI; see \c GetProperty().
     ///
-    /// \param propName The name of the property. Has the same usage as in \c GetProperty.
+    /// @param propName The name of the property. Can be a general path expression, must not be null
+    /// or the empty string; see \c GetProperty() for namespace prefix usage.
     ///
-    /// \param propValue The bool value to be assigned to the property.
+    /// @param propValue The new binary value. Can be null if creating the property. Must be null
+    /// for arrays and non-leaf levels of structs that do not have values.
     ///
-    /// \param options A pointer to the \c XMP_OptionBits variable that is assigned option flags
-    /// describing the property. May be null if the flags are not wanted.
+    /// @param options Option flags describing the property; a logical OR of allowed bit-flag
+    /// constants; see \c #kXMP_PropValueIsStruct and following. Must match the type of a property
+    /// that already exists.
 
-    void
-    SetProperty_Bool ( XMP_StringPtr  schemaNS,
-                       XMP_StringPtr  propName,
-                       bool           propValue,
-                       XMP_OptionBits options = 0 );
+    void SetProperty_Date ( XMP_StringPtr         schemaNS,
+						    XMP_StringPtr         propName,
+						    const XMP_DateTime &  propValue,
+						    XMP_OptionBits        options = 0 );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief \c SetProperty_Int sets the value of an integer property from a C long integer.
+    /// @}
+    // =============================================================================================
+    /// \name Accessing localized text (alt-text) properties.
+    /// @{
     ///
-    /// \param schemaNS The namespace URI for the property. Has the same usage as in \c GetProperty.
+	/// Localized text properties are stored in alt-text arrays. They allow multiple concurrent
+	/// localizations of a property value, for example a document title or copyright in several
+	/// languages.
     ///
-    /// \param propName The name of the property. Has the same usage as in \c GetProperty.
+    /// These functions provide convenient support for localized text properties, including a
+    /// number of special and obscure aspects. The most important aspect of these functions is that
+    /// they select an appropriate array item based on one or two RFC 3066 language tags. One of
+    /// these languages, the "specific" language, is preferred and selected if there is an exact
+    /// match. For many languages it is also possible to define a "generic" language that can be
+    /// used if there is no specific language match. The generic language must be a valid RFC 3066
+    /// primary subtag, or the empty string.
     ///
-    /// \param propValue The long integer value to be assigned to the property.
+    /// For example, a specific language of "en-US" should be used in the US, and a specific
+    /// language of "en-UK" should be used in England. It is also appropriate to use "en" as the
+    /// generic language in each case. If a US document goes to England, the "en-US" title is
+    /// selected by using the "en" generic language and the "en-UK" specific language.
     ///
-    /// \param options Option flags describing the property.
-
-    void
-    SetProperty_Int ( XMP_StringPtr  schemaNS,
-                      XMP_StringPtr  propName,
-                      long           propValue,
-                      XMP_OptionBits options = 0 );
+    /// It is considered poor practice, but allowed, to pass a specific language that is just an
+    /// RFC 3066 primary tag. For example "en" is not a good specific language, it should only be
+    /// used as a generic language. Passing "i" or "x" as the generic language is also considered
+    /// poor practice but allowed.
+    ///
+    /// Advice from the W3C about the use of RFC 3066 language tags can be found at:
+    ///     \li http://www.w3.org/International/articles/language-tags/
+    ///
+    /// \note RFC 3066 language tags must be treated in a case insensitive manner. The XMP toolkit
+    /// does this by normalizing their capitalization:
+ 	/// 	\li The primary subtag is lower case, the suggested practice of ISO 639.
+	/// 	\li All 2 letter secondary subtags are upper case, the suggested practice of ISO 3166.
+	/// 	\li All other subtags are lower case.
+    ///
+    /// The XMP specification defines an artificial language, "x-default", that is used to
+    /// explicitly denote a default item in an alt-text array. The XMP toolkit normalizes alt-text
+    /// arrays such that the x-default item is the first item. The \c SetLocalizedText() function
+    /// has several special features related to the x-default item, see its description for details.
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief \c SetProperty_Int64 sets the value of an integer property from a C long long integer.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c GetLocalizedText() retrieves information about a selected item in an alt-text array.
+    ///
+    /// The array item is selected according to these rules:
+    ///   \li Look for an exact match with the specific language.
+    ///   \li If a generic language is given, look for a partial match.
+    ///   \li Look for an x-default item.
+    ///   \li Choose the first item.
+    ///
+    /// A partial match with the generic language is where the start of the item's language matches
+    /// the generic string and the next character is '-'. An exact match is also recognized as a
+    /// degenerate case.
+    ///
+    /// You can pass "x-default" as the specific language. In this case, selection of an
+    /// \c x-default item is an exact match by the first rule, not a selection by the 3rd rule. The
+    /// last 2 rules are fallbacks used when the specific and generic languages fail to produce a
+    /// match.
     ///
-    /// \param schemaNS The namespace URI for the property. Has the same usage as in \c GetProperty.
+    /// The return value reports whether a match was successfully made.
     ///
-    /// \param propName The name of the property. Has the same usage as in \c GetProperty.
+    /// @param schemaNS The namespace URI for the alt-text array; see \c GetProperty().
     ///
-    /// \param propValue The long long integer value to be assigned to the property.
+    /// @param altTextName The name of the alt-text array. Can be a general path expression, must
+    /// not be null or the empty string; see \c GetProperty() for namespace prefix usage.
     ///
-    /// \param options Option flags describing the property.
+    /// @param genericLang The name of the generic language as an RFC 3066 primary subtag. Can be
+    /// null or the empty string if no generic language is wanted.
+    ///
+    /// @param specificLang The name of the specific language as an RFC 3066 tag, or "x-default".
+    /// Must not be null or the empty string.
+    ///
+    /// @param actualLang [out] A string object in which to return the language of the selected
+    /// array item, if an appropriate array item is found. Can be null if the language is not wanted.
+    ///
+    /// @param itemValue [out] A string object in which to return the value of the array item, if an
+    /// appropriate array item is found. Can be null if the value is not wanted.
+    ///
+    /// @param options A buffer in which to return the option flags that describe the array item, if
+    /// an appropriate array item is found. Can be null if the flags are not wanted.
+    ///
+    /// @return True if an appropriate array item exists.
 
-    void
-    SetProperty_Int64 ( XMP_StringPtr  schemaNS,
-                        XMP_StringPtr  propName,
-                        long long      propValue,
-                        XMP_OptionBits options = 0 );
+    bool GetLocalizedText ( XMP_StringPtr    schemaNS,
+						    XMP_StringPtr    altTextName,
+						    XMP_StringPtr    genericLang,
+						    XMP_StringPtr    specificLang,
+						    tStringObj *     actualLang,
+						    tStringObj *     itemValue,
+						    XMP_OptionBits * options ) const;
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief \c SetProperty_Float sets the value of a floating point property from a C double float.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c SetLocalizedText() modifies the value of a selected item in an alt-text array.
+    ///
+    /// Creates an appropriate array item if necessary, and handles special cases for the x-default
+    /// item.
+    ///
+    /// The array item is selected according to these rules:
+    ///   \li Look for an exact match with the specific language.
+    ///   \li If a generic language is given, look for a partial match.
+    ///   \li Look for an x-default item.
+    ///   \li Choose the first item.
+    ///
+    /// A partial match with the generic language is where the start of the item's language matches
+    /// the generic string and the next character is '-'. An exact match is also recognized as a
+    /// degenerate case.
+    ///
+    /// You can pass "x-default" as the specific language. In this case, selection of an
+    /// \c x-default item is an exact match by the first rule, not a selection by the 3rd rule. The
+    /// last 2 rules are fallbacks used when the specific and generic languages fail to produce a
+    /// match.
+    ///
+    /// Item values are modified according to these rules:
+    ///
+    ///   \li If the selected item is from a match with the specific language, the value of that
+    ///   item is modified. If the existing value of that item matches the existing value of the
+    ///   x-default item, the x-default item is also modified. If the array only has 1 existing item
+    ///   (which is not x-default), an x-default item is added with the given value.
+    ///
+    ///   \li If the selected item is from a match with the generic language and there are no other
+    ///   generic matches, the value of that item is modified. If the existing value of that item
+    ///   matches the existing value of the x-default item, the x-default item is also modified. If
+    ///   the array only has 1 existing item (which is not x-default), an x-default item is added
+    ///   with the given value.
+    ///
+    ///   \li If the selected item is from a partial match with the generic language and there are
+    ///   other partial matches, a new item is created for the specific language. The x-default item
+    ///   is not modified.
+    ///
+    ///   \li If the selected item is from the last 2 rules then a new item is created for the
+    ///   specific language. If the array only had an x-default item, the x-default item is also
+    ///   modified. If the array was empty, items are created for the specific language and
+    ///   x-default.
+    ///
+    /// @param schemaNS The namespace URI for the alt-text array; see \c GetProperty().
+    ///
+    /// @param altTextName The name of the alt-text array. Can be a general path expression, must
+    /// not be null or the empty string; see \c GetProperty() for namespace prefix usage.
     ///
-    /// \param schemaNS The namespace URI for the property. Has the same usage as in \c GetProperty.
+    /// @param genericLang The name of the generic language as an RFC 3066 primary subtag. Can be
+    /// null or the empty string if no generic language is wanted.
     ///
-    /// \param propName The name of the property. Has the same usage as in \c GetProperty.
+    /// @param specificLang The name of the specific language as an RFC 3066 tag, or "x-default".
+    /// Must not be null or the empty string.
     ///
-    /// \param propValue The double float value to be assigned to the property.
+    /// @param itemValue The new value for the matching array item, specified as a null-terminated
+    /// UTF-8 string.
     ///
-    /// \param options Option flags describing the property.
+    /// @param options Option flags, none currently defined.
 
-    void
-    SetProperty_Float ( XMP_StringPtr  schemaNS,
-                        XMP_StringPtr  propName,
-                        double         propValue,
-                        XMP_OptionBits options = 0 );
+    void SetLocalizedText ( XMP_StringPtr  schemaNS,
+						    XMP_StringPtr  altTextName,
+						    XMP_StringPtr  genericLang,
+						    XMP_StringPtr  specificLang,
+						    XMP_StringPtr  itemValue,
+						    XMP_OptionBits options = 0 );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief \c SetProperty_Date sets the value of a date/time property from an \c XMP_DateTime struct.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c SetLocalizedText() modifies the value of a selected item in an alt-text array using
+    /// a string object.
+    ///
+    /// Creates an appropriate array item if necessary, and handles special cases for the x-default
+    /// item.
+    ///
+    /// The array item is selected according to these rules:
+    ///   \li Look for an exact match with the specific language.
+    ///   \li If a generic language is given, look for a partial match.
+    ///   \li Look for an x-default item.
+    ///   \li Choose the first item.
+    ///
+    /// A partial match with the generic language is where the start of the item's language matches
+    /// the generic string and the next character is '-'. An exact match is also recognized as a
+    /// degenerate case.
+    ///
+    /// You can pass "x-default" as the specific language. In this case, selection of an \c x-default
+    /// item is an exact match by the first rule, not a selection by the 3rd rule. The last 2 rules
+    /// are fallbacks used when the specific and generic languages fail to produce a match.
+    ///
+    /// Item values are modified according to these rules:
+    ///
+    ///   \li If the selected item is from a match with the specific language, the value of that
+    ///   item is modified. If the existing value of that item matches the existing value of the
+    ///   x-default item, the x-default item is also modified. If the array only has 1 existing item
+    ///   (which is not x-default), an x-default item is added with the given value.
+    ///
+    ///   \li If the selected item is from a match with the generic language and there are no other
+    ///   generic matches, the value of that item is modified. If the existing value of that item
+    ///   matches the existing value of the x-default item, the x-default item is also modified. If
+    ///   the array only has 1 existing item (which is not x-default), an x-default item is added
+    ///   with the given value.
     ///
-    /// \param schemaNS The namespace URI for the property. Has the same usage as in \c GetProperty.
+    ///   \li If the selected item is from a partial match with the generic language and there are
+    ///   other partial matches, a new item is created for the specific language. The x-default item
+    ///   is not modified.
     ///
-    /// \param propName The name of the property. Has the same usage as in \c GetProperty.
+    ///   \li If the selected item is from the last 2 rules then a new item is created for the
+    ///   specific language. If the array only had an x-default item, the x-default item is also
+    ///   modified. If the array was empty, items are created for the specific language and
+    ///   x-default.
     ///
-    /// \param propValue The \c XMP_DateTime value to be assigned to the property.
+    /// @param schemaNS The namespace URI for the alt-text array; see \c GetProperty().
     ///
-    /// \param options Option flags describing the property.
+    /// @param altTextName The name of the alt-text array. Can be a general path expression, must
+    /// not be null or the empty string; see \c GetProperty() for namespace prefix usage.
+    ///
+    /// @param genericLang The name of the generic language as an RFC 3066 primary subtag. Can be
+    /// null or the empty string if no generic language is wanted.
+    ///
+    /// @param specificLang The name of the specific language as an RFC 3066 tag, or "x-default".
+    /// Must not be null or the empty string.
+    ///
+    /// @param itemValue The new value for the matching array item, specified as a string object.
+    ///
+    /// @param options Option flags, none currently defined.
 
-    void
-    SetProperty_Date ( XMP_StringPtr         schemaNS,
-                       XMP_StringPtr         propName,
-                       const XMP_DateTime &  propValue,
-                       XMP_OptionBits        options = 0 );
+    void SetLocalizedText ( XMP_StringPtr      schemaNS,
+						    XMP_StringPtr      altTextName,
+						    XMP_StringPtr      genericLang,
+						    XMP_StringPtr      specificLang,
+						    const tStringObj & itemValue,
+						    XMP_OptionBits     options = 0 );
 
     /// @}
 
-    // =============================================================================================
-    // Miscellaneous Member Functions
-    // ==============================
-
-    //  --------------------------------------------------------------------------------------------
-    /// \name Misceallaneous functions.
+   	// =============================================================================================
+    /// \name Creating and reading serialized RDF.
     /// @{
+    ///
+	/// The metadata contained in an XMP object must be serialized as RDF for storage in an XMP
+	/// packet and output to a file. Similarly, metadata in the form of serialized RDF (such as
+	/// metadata read from a file using \c TXMPFiles) must be parsed into an XMP object for
+	/// manipulation with the XMP Toolkit.
+	///
+	/// These functions support parsing serialized RDF into an XMP object, and serializing an XMP
+    /// object into RDF. The input for parsing can be any valid Unicode encoding. ISO Latin-1 is
+    /// also recognized, but its use is strongly discouraged. Serialization is always as UTF-8.
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief GetInternalRef Returns an internal reference that may be safely passed across DLL
-    /// boundaries and reconstructed.
-
-    XMPMetaRef
-    GetInternalRef() const;
-
-    //  --------------------------------------------------------------------------------------------
-    /// \brief GetObjectName --TBD--
-
-    void
-    GetObjectName ( tStringObj * name ) const;
-
-    //  --------------------------------------------------------------------------------------------
-    /// \brief SetObjectName --TBD--
-
-    void
-    SetObjectName ( XMP_StringPtr name );
-
-    //  --------------------------------------------------------------------------------------------
-    /// \brief SetObjectName --TBD--
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c ParseFromBuffer() parses RDF from a series of input buffers into this XMP object.
+    ///
+    /// Use this to convert metadata from serialized RDF form (as, for example, read from an XMP
+    /// packet embedded in a file) into an XMP object that you can manipulate with the XMP Toolkit.
+    /// If this XMP object is empty and the input buffer contains a complete XMP packet, this is the
+    /// same as creating a new XMP object from that buffer with the constructor.
+    ///
+    /// You can use this function to combine multiple buffers into a single metadata tree. To
+    /// terminate an input loop conveniently, pass  the option \c #kXMP_ParseMoreBuffers for all
+    /// real input, then make a final call with a zero length and \c #kXMP_NoOptions. The buffers
+    /// can be any length. The buffer boundaries need not respect XML tokens or even Unicode
+    /// characters.
+    ///
+    /// @param buffer A pointer to a buffer of input. Can be null if \c bufferSize is 0.
+    ///
+    /// @param bufferSize The length of the input buffer in bytes. Zero is a valid value.
+    ///
+    /// @param options An options flag that controls how the parse operation is performed. A logical
+    /// OR of these bit-flag constants:
+    ///   \li \c #kXMP_ParseMoreBuffers - This is not the last buffer of input, more calls follow.
+    ///   \li \c #kXMP_RequireXMPMeta - The \c x:xmpmeta XML element is required around \c rdf:RDF.
+    ///
+    /// @see \c TXMPFiles::GetXMP()
+
+    void ParseFromBuffer ( XMP_StringPtr  buffer,
+						   XMP_StringLen  bufferSize,
+						   XMP_OptionBits options = 0 );
+
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c SerializeToBuffer() serializes metadata in this XMP object into a string as RDF.
+    ///
+    /// Use this to prepare metadata for storage as an XMP packet embedded in a file. See \c TXMPFiles::PutXMP().
+    ///
+    /// @param rdfString [out] A string object in which to return the serialized RDF. Must not be null.
+    ///
+    /// @param options An options flag that controls how the serialization operation is performed.
+    /// The specified options must be logically consistent; an exception is thrown if they are not.
+    /// A logical OR of these bit-flag constants:
+    ///   \li \c kXMP_OmitPacketWrapper - Do not include an XML packet wrapper. This cannot be
+    ///   specified together with \c #kXMP_ReadOnlyPacket, \c #kXMP_IncludeThumbnailPad, or
+    ///   \c #kXMP_ExactPacketLength.
+    ///   \li \c kXMP_ReadOnlyPacket - Create a read-only XML packet wapper. Cannot be specified
+    ///   together with \c kXMP_OmitPacketWrapper.
+    ///   \li \c kXMP_UseCompactFormat - Use a highly compact RDF syntax and layout.
+    ///   \li \c kXMP_WriteAliasComments - Include XML comments for aliases.
+    ///   \li \c kXMP_IncludeThumbnailPad - Include typical space for a JPEG thumbnail in the
+    ///   padding if no \c xmp:Thumbnails property is present. Cannot be specified together with
+    ///   \c kXMP_OmitPacketWrapper.
+    ///   \li \c kXMP_ExactPacketLength - The padding parameter provides the overall packet length.
+    ///   The actual amount of padding is computed. An exception is thrown if the packet exceeds
+    ///   this length with no padding.	Cannot be specified together with
+    ///   \c kXMP_OmitPacketWrapper.
+    ///
+    /// In addition to the above options, you can include one of the following encoding options:
+    ///   \li \c #kXMP_EncodeUTF8 - Encode as UTF-8, the default.
+    ///   \li \c #kXMP_EncodeUTF16Big - Encode as big-endian UTF-16.
+    ///   \li \c #kXMP_EncodeUTF16Little - Encode as little-endian UTF-16.
+    ///   \li \c #kXMP_EncodeUTF32Big - Encode as big-endian UTF-32.
+    ///   \li \c #kXMP_EncodeUTF32Little - Encode as little-endian UTF-32.
+    ///
+    /// @param padding The amount of padding to be added if a writeable XML packet is created. If
+    /// zero (the default) an appropriate amount of padding is computed.
+    ///
+    /// @param newline The string to be used as a line terminator. If empty, defaults to linefeed,
+    /// U+000A, the standard XML newline.
+    ///
+    /// @param indent The string to be used for each level of indentation in the serialized RDF. If
+    /// empty, defaults to two ASCII spaces, U+0020.
+    ///
+    /// @param baseIndent The number of levels of indentation to be used for the outermost XML
+    /// element in the serialized RDF. This is convenient when embedding the RDF in other text.
 
-    void
-    SetObjectName ( tStringObj name );
+    void SerializeToBuffer ( tStringObj *   rdfString,
+							 XMP_OptionBits options,
+							 XMP_StringLen  padding,
+							 XMP_StringPtr  newline,
+							 XMP_StringPtr  indent = "",
+							 XMP_Index      baseIndent = 0 ) const;
+
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c SerializeToBuffer() serializes metadata in this XMP object into a string as RDF.
+    ///
+    /// This simpler form of the function uses default values for the \c newline, \c indent, and
+    /// \c baseIndent parameters.
+    ///
+    /// @param rdfString [out] A string object in which to return the serialized RDF. Must not be null.
+    ///
+    /// @param options An options flag that controls how the serialization operation is performed.
+    /// The specified options must be logically consistent; an exception is thrown if they are not.
+    /// A logical OR of these bit-flag constants:
+    ///   \li \c kXMP_OmitPacketWrapper - Do not include an XML packet wrapper. This cannot be
+    ///   specified together with \c #kXMP_ReadOnlyPacket, \c #kXMP_IncludeThumbnailPad, or
+    ///   \c #kXMP_ExactPacketLength.
+    ///   \li \c kXMP_ReadOnlyPacket - Create a read-only XML packet wapper. Cannot be specified
+    ///   together with \c kXMP_OmitPacketWrapper.
+    ///   \li \c kXMP_UseCompactFormat - Use a highly compact RDF syntax and layout.
+    ///   \li \c kXMP_WriteAliasComments - Include XML comments for aliases.
+    ///   \li \c kXMP_IncludeThumbnailPad - Include typical space for a JPEG thumbnail in the
+    ///   padding if no \c xmp:Thumbnails property is present. Cannot be specified together with
+    ///   \c kXMP_OmitPacketWrapper.
+    ///   \li \c kXMP_ExactPacketLength - The padding parameter provides the overall packet length.
+    ///   The actual amount of padding is computed. An exception is thrown if the packet exceeds
+    ///   this length with no padding.	Cannot be specified together with
+    ///   \c kXMP_OmitPacketWrapper.
+    ///
+    /// In addition to the above options, you can include one of the following encoding options:
+    ///   \li \c #kXMP_EncodeUTF8 - Encode as UTF-8, the default.
+    ///   \li \c #kXMP_EncodeUTF16Big - Encode as big-endian UTF-16.
+    ///   \li \c #kXMP_EncodeUTF16Little - Encode as little-endian UTF-16.
+    ///   \li \c #kXMP_EncodeUTF32Big - Encode as big-endian UTF-32.
+    ///   \li \c #kXMP_EncodeUTF32Little - Encode as little-endian UTF-32.
+    ///
+    /// @param padding The amount of padding to be added if a writeable XML packet is created.
+    /// If zero (the default) an appropriate amount of padding is computed.
+
+    void SerializeToBuffer ( tStringObj *   rdfString,
+							 XMP_OptionBits options = 0,
+							 XMP_StringLen  padding = 0 ) const;
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief GetObjectOptions --TBD--
+    /// @}
+    // =============================================================================================
+    // Miscellaneous Member Functions
+    // ==============================
 
-    XMP_OptionBits
-    GetObjectOptions() const;
+    // ---------------------------------------------------------------------------------------------
+    /// \name Helper functions.
+    /// @{
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief SetObjectOptions --TBD--
+    // ---------------------------------------------------------------------------------------------
+    /// @brief Retrieves an internal reference that can be safely passed across DLL boundaries and
+    /// reconstructed.
     ///
-    /// \note <b>Not yet implemented.</b> File a bug if you need this.
-
-    void
-    SetObjectOptions ( XMP_OptionBits options );
-
-    //  --------------------------------------------------------------------------------------------
-    /// \brief \c Clone creates a deep clone of the XMP object.
+    /// The \c TXMPMeta class is a normal C++ template, it is instantiated and local to each client
+    /// executable, as are the other \c TXMP* classes. Different clients might not use the same
+    /// string type to instantiate \c TXMPMeta.
     ///
-    /// This function creates a deep clone of the XMP object. Assignment and copy constructors do
-    /// not, they just increment a reference count. Note that \c Clone returns an object, not a
-    /// pointer. This is easy to misuse:
+    /// Because of this you should not pass \c SXMPMeta objects, or pointers to \c SXMPMeta objects,
+    /// across DLL boundaries. Use this function to obtain a safe internal reference that you can
+    /// pass, then construct a local object on the callee side. This construction does not create a
+    /// cloned XMP tree, it is the same underlying XMP object safely wrapped in each client's
+    /// \c SXMPMeta object.
     ///
-    /// \code
-    ///		SXMPMeta * clone1 = &sourceXMP.Clone();                  // ! This does not work!
-    ///		SXMPMeta * clone2 = new SXMPMeta ( sourceXMP.Clone() );  // This works.
-    ///		SXMPMeta   clone3 ( sourceXMP.Clone );  // This works also. (Not a pointer.)
-    /// \endcode
+    /// Use this function and the associated constructor like this:
+    ///   \li The callee's header contains:
+    /// <pre>
+    /// CalleeMethod ( XMPMetaRef xmpRef );
+    /// </pre>
     ///
-    /// In the code above, the assignment to \c clone1 creates a temporary object, initializes it
-    /// with the clone, assigns the address of the temporary to \c clone1, then deletes the
-    /// temporary. The \c clone3 example also works, you do not have to use an explicit pointer.
-    /// This is good for local usage, you don't have to worry about memory leaks.
+    ///   \li The caller's code contains:
+    /// <pre>
+    /// SXMPMeta callerXMP;
+    /// CalleeMethod ( callerXMP.GetInternalRef() );
+    /// </pre>
     ///
-    /// \param options Option flags, not are defined at present.
+    ///   \li The callee's code contains:
+    /// <pre>
+    /// SXMPMeta calleeXMP ( xmpRef );
+    /// </pre>
     ///
-    /// \result An XMP object cloned from the original.
+    /// @return The reference object.
 
-    TXMPMeta
-    Clone ( XMP_OptionBits options = 0 ) const;
+    XMPMetaRef GetInternalRef() const;
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief CountArrayItems --TBD--
-
-    XMP_Index
-    CountArrayItems ( XMP_StringPtr schemaNS,
-                      XMP_StringPtr arrayName ) const;
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c GetObjectName() retrieves the client-assigned name of this XMP object.
+    ///
+    /// Assign this name with \c SetObjectName().
+    ///
+    /// @param name [out] A string object in which to return the name.
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief \c DumpObject dumps the content of an XMP object.
+    void GetObjectName ( tStringObj * name ) const;
 
-    XMP_Status
-    DumpObject ( XMP_TextOutputProc outProc,
-                 void *             refCon ) const;
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c SetObjectName() assigns a name to this XMP object.
+    ///
+    /// Retrieve this client-assigned name with \c GetObjectName().
+    ///
+    /// @param name The name as a null-terminated UTF-8 string.
 
-    /// @}
+    void SetObjectName ( XMP_StringPtr name );
 
-    // =============================================================================================
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c SetObjectName() assigns a name to this XMP object.
+    ///
+    /// Retrieve this client-assigned name with \c GetObjectName().
+    ///
+    /// @param name The name as a string object.
 
-    //  --------------------------------------------------------------------------------------------
-    /// \name Functions for parsing and serializing.
-    /// @{
-	/// These functions support parsing serialized RDF into an XMP object, and serailizing an XMP
-    /// object into RDF. The input for parsing may be any valid Unicode encoding. ISO Latin-1 is
-    /// also recognized, but its use is strongly discouraged. Serialization is always as UTF-8.
+    void SetObjectName ( tStringObj name );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief \c ParseFromBuffer parses RDF from a series of input buffers. The buffers may be any
-    /// length. The buffer boundaries need not respect XML tokens or even Unicode characters.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c Sort() sorts the data model tree of an XMP object.
     ///
-    /// \param buffer A pointer to a buffer of input. May be null if \c bufferSize is 0.
+    /// Use this function to sort the data model of an XMP object into a canonical order. This can
+    /// be convenient when comparing data models, (e.g. by text comparison of DumpObject output).
+    ///
+    /// At the top level the namespaces are sorted by their prefixes. Within a namespace, the top
+    /// level properties are sorted by name. Within a struct, the fields are sorted by their
+    /// qualified name, i.e. their XML prefix:local form. Unordered arrays of simple items are
+    /// sorted by value. Language Alternative arrays are sorted by the xml:lang qualifiers, with
+    /// the "x-default" item placed first.
+    
+    void Sort();
+
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c Erase() restores the object to a "just constructed" state.
+    
+    void Erase();
+    
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c Clone() creates a deep copy of an XMP object.
     ///
-    /// \param bufferSize The length of this buffer in bytes. Zero is a valid value. Termination of
-    /// an input loop is convenient by passing \c kXMP_ParseMoreBuffers for all real input, then
-    /// having a final call with a zero length and \c kXMP_NoOptions.
+    /// Use this function to copy an entire XMP metadata tree. Assignment and copy constructors only
+    /// increment a reference count, they do not do a deep copy. This function returns an object,
+    /// not a pointer. The following shows correct usage:
     ///
-    /// \param options Options controlling the parsing.
+    /// <pre>
+    /// SXMPMeta * clone1 = new SXMPMeta ( sourceXMP.Clone() );  // This works.
+    /// SXMPMeta   clone2 ( sourceXMP.Clone );  	// This works also. (Not a pointer.)
+    /// </pre>
+    /// The \c clone2 example does not use an explicit pointer.
+    /// This is good for local usage, protecting against memory leaks.
     ///
-    /// The available options are:
+    /// This is an example of incorrect usage:
+    /// <pre>
+    /// SXMPMeta * clone3 = &sourceXMP.Clone();		// ! This does not work!
+    /// </pre>
+    /// The assignment to \c clone3 creates a temporary object, initializes it with the clone,
+    /// assigns the address of the temporary to \c clone3, then deletes the temporary.
     ///
-    /// \li \c kXMP_ParseMoreBuffers - This is not the last buffer of input, more calls follow.
-    /// \li \c kXMP_RequireXMPMeta - The x:xmpmeta XML element is required around <tt>rdf:RDF</tt>.
-    /// \li \c kXMP_StrictAliasing - Do not reconcile alias differences, throw an exception.
+    /// @param options Option flags, not currently defined..
     ///
-    /// \note The \c kXMP_StrictAliasing option is not yet implemented.
+    /// @return An XMP object cloned from the original.
 
-    void
-    ParseFromBuffer ( XMP_StringPtr  buffer,
-                      XMP_StringLen  bufferSize,
-                      XMP_OptionBits options = 0 );
+    TXMPMeta Clone ( XMP_OptionBits options = 0 ) const;
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief \c SerializeToBuffer serializes an XMP object into a string as RDF.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c CountArrayItems() reports the number of items currently defined in an array.
     ///
-    /// \param rdfString A pointer to the string to receive the serialized RDF. Must not be null.
+    /// @param schemaNS The namespace URI; see \c GetProperty().
     ///
-    /// \param options Option flags to control the serialization.
+    /// @param arrayName The name of the array. Can be a general path expression, must not be null
+    /// or the empty string; see \c GetProperty() for namespace prefix usage.
     ///
-    /// \param padding The amount of padding to be added if a writeable XML packet is created. If
-    /// zero is passed (the default) an appropriate amount of padding is computed.
+    /// @return The number of items.
+
+    XMP_Index CountArrayItems ( XMP_StringPtr schemaNS,
+                      			XMP_StringPtr arrayName ) const;
+
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c DumpObject() outputs the content of an XMP object to a callback handler for debugging.
     ///
-    /// \param newline The string to be used as a line terminator. If empty it defaults to
-    /// linefeed, U+000A, the standard XML newline.
+    /// Invokes a client-defined callback for each line of output.
     ///
-    /// \param indent The string to be used for each level of indentation in the serialized RDF. If
-    /// empty it defaults to two ASCII spaces, U+0020.
+    /// @param outProc The client-defined procedure to handle each line of output.
     ///
-    /// \param baseIndent The number of levels of indentation to be used for the outermost XML
-    /// element in the serialized RDF. This is convenient when embedding the RDF in other text.
+    /// @param clientData A pointer to client-defined data to pass to the handler.
+    ///
+    /// @return	A success-fail status value, returned from the handler. Zero is success, failure
+    /// values are client-defined.
     ///
-    /// The available option flags are:
-    ///
-    /// \li \c kXMP_OmitPacketWrapper - Do not include an XML packet wrapper.
-    /// \li \c kXMP_ReadOnlyPacket - Create a read-only XML packet wapper.
-    /// \li \c kXMP_UseCompactFormat - Use a highly compact RDF syntax and layout.
-    /// \li \c kXMP_WriteAliasComments - Include XML comments for aliases.
-    /// \li \c kXMP_IncludeThumbnailPad - Include typical space for a JPEG thumbnail in the padding
-    /// if no <tt>xmp:Thumbnails</tt> property is present.
-    /// \li \c kXMP_ExactPacketLength - The padding parameter provides the overall packet length.
-    /// The actual amount of padding is computed. An exception is thrown if the packet exceeds this
-    /// length with no padding.
-    ///
-    /// The specified options must be logically consistent, an exception is thrown if not. You
-    /// cannot specify both \c kXMP_OmitPacketWrapper along with \c kXMP_ReadOnlyPacket, \c
-    /// kXMP_IncludeThumbnailPad, or \c kXMP_ExactPacketLength.
-    ///
-    /// In addition, one of the following encoding options may be included:
-    ///
-    /// \li \c kXMP_EncodeUTF8 - Encode as UTF-8, the default.
-    /// \li \c kXMP_EncodeUTF16Big - Encode as big-endian UTF-16.
-    /// \li \c kXMP_EncodeUTF16Little - Encode as little-endian UTF-16.
-    /// \li \c kXMP_EncodeUTF32Big - Encode as big-endian UTF-32.
-    /// \li \c kXMP_EncodeUTF32Little - Encode as little-endian UTF-32.
-
-    void
-    SerializeToBuffer ( tStringObj *   rdfString,
-                        XMP_OptionBits options,
-                        XMP_StringLen  padding,
-                        XMP_StringPtr  newline,
-                        XMP_StringPtr  indent = "",
-                        XMP_Index      baseIndent = 0 ) const;
-
-    //  --------------------------------------------------------------------------------------------
-    /// \brief This form of \c SerializeToBuffer is a simple overload in the template that calls the
-    /// above form passing default values for the \c newline, \c indent, and \c baseIndent
-    /// parameters.
-
-    void
-    SerializeToBuffer ( tStringObj *   rdfString,
-                        XMP_OptionBits options = 0,
-                        XMP_StringLen  padding = 0 ) const;
+    /// @see Static functions \c DumpNamespaces() and \c DumpAliases()
+
+    XMP_Status DumpObject ( XMP_TextOutputProc outProc,
+                 			void *	           clientData ) const;
+
+    // ---------------------------------------------------------------------------------------------
+    /// @brief Not implemented
+    XMP_OptionBits GetObjectOptions() const;
+
+    // ---------------------------------------------------------------------------------------------
+    /// \brief Not implemented
+    void SetObjectOptions ( XMP_OptionBits options );
 
     /// @}
 
diff --git a/public/include/TXMPUtils.hpp b/public/include/TXMPUtils.hpp
index 95cdc9c..4c69edd 100644
--- a/public/include/TXMPUtils.hpp
+++ b/public/include/TXMPUtils.hpp
@@ -7,41 +7,46 @@
 
 // =================================================================================================
 // ADOBE SYSTEMS INCORPORATED
-// Copyright 2002-2007 Adobe Systems Incorporated
+// Copyright 2002-2008 Adobe Systems Incorporated
 // All Rights Reserved
 //
 // NOTICE: Adobe permits you to use, modify, and distribute this file in accordance with the terms
 // of the Adobe license agreement accompanying it.
 // =================================================================================================
 
-//  ================================================================================================
+// =================================================================================================
 /// \file TXMPUtils.hpp
-/// \brief Template class for the XMP Toolkit utility services.
+/// \brief API for access to the XMP Toolkit utility services.
 ///
-/// \c TXMPUtils is the template class providing utility services for the XMP Toolkit. It should be
-/// instantiated with a string class such as <tt>std::string</tt>. Please read the general toolkit
-/// usage notes for information about the overall architecture of the XMP API.
-//  ================================================================================================
+/// \c TXMPUtils is the template class providing utility services for the XMP Toolkit. It must be
+/// instantiated with a string class such as \c std::string. See the instructions in XMP.hpp, and
+/// the Overview for a discussion of the overall architecture of the XMP API.
+// =================================================================================================
 
-//  ================================================================================================
+// =================================================================================================
 /// \class TXMPUtils TXMPUtils.hpp
-/// \brief Template class for the XMP Toolkit utility services.
+/// @brief API for access to the XMP Toolkit utility services.
 ///
-/// \c TXMPUtils is the template class providing utility services for the XMP Toolkit. It should be
-/// instantiated with a string class such as <tt>std::string</tt>. Please read the general toolkit
-/// usage notes for information about the overall architecture of the XMP API.
+/// \c TXMPUtils is a template class which must be instantiated with a string class such as
+/// \c std::string. See the instructions in XMP.hpp, and the Overview for a discussion of the overall
+/// architecture of the XMP API.
 ///
-/// This is a class for C++ scoping purposes only. It has only static functions, you cannot create
-/// an object. These are all functions that layer cleanly on top of the core XMP toolkit. The
-/// template wraps a string class around the raw XMP API, so that output strings are automatically
-/// copied and access is fully thread safe.  String objects are only necessary for output strings.
-/// Input strings are literals and passed as typical C <tt>const char *</tt>.
+/// This class defines helper functions that support the basic metadata manipulation provided by
+/// \c TXMPMeta. All of the functions are static; that is, you call them directly from the concrete
+/// class (\c SXMPUtils), which is never itself instantiated.
 ///
-/// The template parameter, class \c TtStringObj, is described in the XMP.hpp umbrella header.
-//  ================================================================================================
+/// General categories of utilities include:
+///
+///   \li Composing complex path expressions, which you can then pass to the property access
+///   functions in \c TXMPMeta
+///   \li Converting between binary and string forms of property values
+///   \li Manipulating date/time values
+///   \li Encoding and decoding base-64 strings
+///   \li JPEG file handling
+///   \li Editing aids for creating a user interface for the XMP Toolkit
+// =================================================================================================
 
-template <class tStringObj>
-class TXMPUtils {
+template <class tStringObj> class TXMPUtils {
 
 public:
 
@@ -49,795 +54,910 @@ public:
     // No constructors or destructor declared or needed
     // ================================================
 
-    // =============================================================================================
-    // =============================================================================================
-
     //  ============================================================================================
-    /// \name Path composition functions
+    /// \name Path composition
     /// @{
+    ///
     /// These functions provide support for composing path expressions to deeply nested properties.
-    /// The functions in \c TXMPMeta such as \c GetProperty, \c GetArrayItem, and \c GetStructField
-    /// provide easy access to top level simple properties, items in top level arrays, and fields
-    /// of top level structs. They do not provide convenient access to more complex things like
-    /// fields several levels deep in a complex struct, or fields within an array of structs, or
-    /// items of an array that is a field of a struct. These functions can also be used to compose
-    /// paths to top level array items or struct fields so that you can use the binary accessors
-    /// like \c GetProperty_Int.
+    /// The functions in \c TXMPMeta such as \c TXMPMeta::GetProperty(),
+    /// \c TXMPMeta::GetArrayItem(), and \c TXMPMeta::GetStructField() provide easy access to top level
+    /// simple properties, items in top level arrays, and fields of top level structs.	They are
+    /// not as convenient for more complex things, such as fields several levels deep in a complex
+    /// struct, or fields within an array of structs, or items of an array that is a field of a
+    /// struct. You can use these utility functions to compose these paths, which you can then pass
+    /// to the property access functions. You can also compose	paths to top-level array items or
+	/// struct fields so that you can use the binary accessors such as
+	/// \c TXMPMeta::GetProperty_Int().
     ///
     /// You can use these functions is to compose a complete path expression, or all but the last
-    /// component. Suppose you have a property that is an array of integers within a struct. You can
-    /// access one of the array items like this:
+    /// component. For example, suppose you have a property that is an array of integers within a
+    /// struct. You can access one of the array items like this:
     ///
-    /// \verbatim
-    ///  SXMPUtils::ComposeStructFieldPath ( schemaNS, "Struct", fieldNS, "Array", &path );
-    ///  SXMPUtils::ComposeArrayItemPath ( schemaNS, path, index, &path );
-    ///  exists = xmpObj.GetProperty_Int ( schemaNS, path, &value, &options );
-    /// \endverbatim
+    /// <pre>
+    ///   SXMPUtils::ComposeStructFieldPath ( schemaNS, "Struct", fieldNS, "Array", &path );
+    ///   SXMPUtils::ComposeArrayItemPath ( schemaNS, path, index, &path );
+    ///   exists = xmpObj.GetProperty_Int ( schemaNS, path, &value, &options );
+    /// </pre>
     ///
     /// You could also use this code if you want the string form of the integer:
     ///
-    /// \verbatim
-    ///  SXMPUtils::ComposeStructFieldPath ( schemaNS, "Struct", fieldNS, "Array", &path );
-    ///  xmpObj.GetArrayItem ( schemaNS, path, index, &value, &options );
-    /// \endverbatim
+    /// <pre>
+    ///   SXMPUtils::ComposeStructFieldPath ( schemaNS, "Struct", fieldNS, "Array", &path );
+    ///   xmpObj.GetArrayItem ( schemaNS, path, index, &value, &options );
+    /// </pre>
     ///
     /// \note It might look confusing that the \c schemaNS is passed in all of the calls above. This
-    /// is because the XMP toolkit keeps the top level "schema" namespace separate from the rest
-    /// of the path expression.
+    /// is because the XMP Toolkit keeps the top-level "schema" namespace separate from the rest of
+    /// the path expression.
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Compose the path expression for an item in an array.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c ComposeArrayItemPath() composes the path expression for an item in an array.
     ///
-    /// \param schemaNS The namespace URI for the array. Must not be null or the empty string.
+    /// The returned string is in the form <tt>ns:arrayName[i]</tt>, where "ns" is the prefix for
+    /// the specified namespace, and "i" is the decimal representation of specified item index.
+    /// If the last item was specified, the path is <tt>ns:arrayName[last()]</tt>.
     ///
-    /// \param arrayName The name of the array. May be a general path expression, must not be null
-    /// or the empty string.
+    /// @param schemaNS The namespace URI for the array; see \c GetProperty().
+    ///
+    /// @param arrayName The name of the array. Can be a general path expression, must not be null
+    /// or the empty string; see \c GetProperty() for namespace prefix usage.
     ///
-    /// \param itemIndex The index of the desired item. Arrays in XMP are indexed from 1. The
-    /// constant \c kXMP_ArrayLastItem always refers to the last existing array item.
+    /// @param itemIndex The 1-based index of the desired item. Use the macro
+    /// \c #kXMP_ArrayLastItem to specify the last existing array item.
     ///
-    /// \param fullPath A pointer to the string that will be assigned the composed path. This will
-    /// be of the form <tt>ns:arrayName[i]</tt>, where "ns" is the prefix for \c schemaNS and "i"
-    /// is the decimal representation of \c itemIndex. If the value of \c itemIndex is
-    /// \c kXMP_ArrayLastItem, the path is <tt>ns:arrayName[last()]</tt>.
+    /// @param fullPath [out] A string in which to return the composed path.
 
-    static void
-    ComposeArrayItemPath ( XMP_StringPtr schemaNS,
-                           XMP_StringPtr arrayName,
-                           XMP_Index     itemIndex,
-                           tStringObj *  fullPath );
+    static void ComposeArrayItemPath ( XMP_StringPtr schemaNS,
+									   XMP_StringPtr arrayName,
+									   XMP_Index     itemIndex,
+									   tStringObj *  fullPath );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Compose the path expression for a field in a struct.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c ComposeStructFieldPath() composes the path expression for a field in a struct.
     ///
-    /// \param schemaNS The namespace URI for the struct. Must not be null or the empty string.
+    /// The returned string is in the form <tt>ns:structName/fNS:fieldName</tt>, where "ns" is the
+    /// prefix for the schema namespace, and "fNS" is the prefix for field namespace.
     ///
-    /// \param structName The name of the struct. May be a general path expression, must not be null
-    /// or the empty string.
+    /// @param schemaNS The namespace URI for the struct; see \c GetProperty().
     ///
-    /// \param fieldNS The namespace URI for the field. Must not be null or the empty string.
+    /// @param structName The name of the struct. Can be a general path expression, must not be null
+    /// or the empty string; see \c GetProperty() for namespace prefix usage.
     ///
-    /// \param fieldName The name of the field. Must be a simple XML name, must not be null or the
-    /// empty string.
+    /// @param fieldNS The namespace URI for the field. Same URI and prefix usage as the
+    /// \c schemaNS and \c structName parameters.
     ///
-    /// \param fullPath A pointer to the string that will be assigned the composed path. This will
-    /// be of the form <tt>ns:structName/fNS:fieldName</tt>, where "ns" is the prefix for
-    /// \c schemaNS and "fNS" is the prefix for \c fieldNS.
+    /// @param fieldName The name of the field. Must be a single XML name, must not be null or the
+    /// empty string. Same URI and prefix usage as the \c schemaNS and \c structName parameters.
+    ///
+    /// @param fullPath [out] A string in which to return the composed path.
 
-    static void
-    ComposeStructFieldPath ( XMP_StringPtr schemaNS,
-                             XMP_StringPtr structName,
-                             XMP_StringPtr fieldNS,
-                             XMP_StringPtr fieldName,
-                             tStringObj *  fullPath );
+    static void ComposeStructFieldPath ( XMP_StringPtr schemaNS,
+										 XMP_StringPtr structName,
+										 XMP_StringPtr fieldNS,
+										 XMP_StringPtr fieldName,
+										 tStringObj *  fullPath );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Compose the path expression for a qualifier.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c ComposeQualifierPath() composes the path expression for a qualifier.
+    ///
+    /// The returned string is in the form <tt>ns:propName/?qNS:qualName</tt>, where "ns" is the
+    /// prefix for the schema namespace, and "qNS" is the prefix for the qualifier namespace.
     ///
-    /// \param schemaNS The namespace URI for the property to which the qualifier is attached. Must
-    /// not be null or the empty string.
+    /// @param schemaNS The namespace URI; see \c GetProperty().
     ///
-    /// \param propName The name of the property to which the qualifier is attached. May be a general
-    /// path expression, must not be null or the empty string.
+    /// @param propName The name of the property to which the qualifier is attached. Can be a
+    /// general path expression, must not be null or the empty string; see \c GetProperty() for
+    /// namespace prefix usage.
     ///
-    /// \param qualNS The namespace URI for the qualifier. May be null or the empty string if the
-    /// qualifier is in the XML empty namespace.
+    /// @param qualNS The namespace URI for the qualifier. Same URI and prefix usage as the
+    /// \c schemaNS and \c propName parameters.
     ///
-    /// \param qualName The name of the qualifier. Must be a simple XML name, must not be null or the
-    /// empty string.
+    /// @param qualName The name of the qualifier. Must be a single XML name, must not be null or the
+    /// empty string. Same URI and prefix usage as the \c schemaNS and \c propName parameters.
     ///
-    /// \param fullPath A pointer to the string that will be assigned the composed path. This will
-    /// be of the form <tt>ns:propName/?qNS:qualName</tt>, where "ns" is the prefix for \c schemaNS
-    /// and "qNS" is the prefix for \c qualNS.
+    /// @param fullPath [out] A string in which to return the composed path.
 
-    static void
-    ComposeQualifierPath ( XMP_StringPtr schemaNS,
-                           XMP_StringPtr propName,
-                           XMP_StringPtr qualNS,
-                           XMP_StringPtr qualName,
-                           tStringObj *  fullPath );
+    static void ComposeQualifierPath ( XMP_StringPtr schemaNS,
+									   XMP_StringPtr propName,
+									   XMP_StringPtr qualNS,
+									   XMP_StringPtr qualName,
+									   tStringObj *  fullPath );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Compose the path expression to select an alternate item by language.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c ComposeLangSelector() composes the path expression to select an alternate item by language.
     ///
-    /// The path syntax allows two forms of "content addressing" that may be used to select an item
-    /// in an array of alternatives. The form used in \c ComposeLangSelector lets you select an
-    /// item in an alt-text array based on the value of its <tt>xml:lang</tt> qualifier. The other
-    /// form of content addressing is shown in \c ComposeFieldSelector.
+    /// Path syntax allows two forms of "content addressing" to select an item in an array of
+    /// alternatives. The form used in this function lets you select an item in an alt-text array
+    /// based on the value of its \c xml:lang qualifier. The other form of content addressing is
+    /// shown in \c ComposeFieldSelector().
     ///
-    /// \note \c ComposeLangSelector does not supplant \c SetLocalizedText or \c GetLocalizedText.
-    /// They should generally be used, as they provide extra logic to choose the appropriate
-    /// language and maintain consistency with the 'x-default' value. \c ComposeLangSelector gives
-    /// you an path expression that is explicitly and only for the language given in the
-    /// \c langName parameter.
+    /// The returned string is in the form <tt>ns:arrayName[\@xml:lang='langName']</tt>, where
+    /// "ns" is the prefix for the schema namespace
     ///
-    /// \param schemaNS The namespace URI for the array. Must not be null or the empty string.
+    /// This function provides a path expression that is explicitly and only for a specific
+    /// language. In most cases, \c TXMPMeta::SetLocalizedText() and \c TXMPMeta::GetLocalizedText()
+    /// are preferred, because they provide extra logic to choose the appropriate language and
+    /// maintain consistency with the 'x-default' value.
     ///
-    /// \param arrayName The name of the array. May be a general path expression, must not be null
-    /// or the empty string.
+    /// @param schemaNS The namespace URI for the array; see \c GetProperty().
     ///
-    /// \param langName The RFC 3066 code for the desired language.
+    /// @param arrayName The name of the array. Can be a general path expression, must not be null
+    /// or the empty string; see \c GetProperty() for namespace prefix usage.
     ///
-    /// \param fullPath A pointer to the string that will be assigned the composed path. This will
-    /// be of the form <tt>ns:arrayName[\@xml:lang='langName']</tt>,
-    /// where "ns" is the prefix for \c schemaNS.
+    /// @param langName The RFC 3066 code for the desired language, as a null-terminated UTF-8 string.
+    ///
+    /// @param fullPath [out] A string in which to return the composed path.
 
-    static void
-    ComposeLangSelector ( XMP_StringPtr schemaNS,
-                          XMP_StringPtr arrayName,
-                          XMP_StringPtr langName,
-                          tStringObj *  fullPath );
+    static void ComposeLangSelector ( XMP_StringPtr schemaNS,
+									  XMP_StringPtr arrayName,
+									  XMP_StringPtr langName,
+									  tStringObj *  fullPath );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief This form of \c ComposeLangSelector is a simple overload in the template that calls
-    /// the above form passing <tt>langName.c_str()</tt>.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c ComposeLangSelector() composes a path expression to select an alternate item by language.
+    ///
+    /// Path syntax allows two forms of "content addressing" to select an item in an array of
+    /// alternatives. The form used in this function lets you select an item in an alt-text array
+    /// based on the value of its \c xml:lang qualifier. The other form of content addressing is
+    /// shown in \c ComposeFieldSelector().
+    ///
+    /// The returned string is in the form <tt>ns:arrayName[\@xml:lang='langName']</tt>, where
+    /// "ns" is the prefix for the schema namespace
+    ///
+    /// This function provides a path expression that is explicitly and only for a specific
+    /// language. In most cases, \c TXMPMeta::SetLocalizedText() and \c TXMPMeta::GetLocalizedText()
+    /// are preferred, because they provide extra logic to choose the appropriate language and
+    /// maintain consistency with the 'x-default' value.
+    ///
+    /// @param schemaNS The namespace URI for the array; see \c GetProperty().
+    ///
+    /// @param arrayName The name of the array. Can be a general path expression, must not be null
+    /// or the empty string; see \c GetProperty() for namespace prefix usage.
+    ///
+    /// @param langName The RFC 3066 code for the desired language, as a string object.
+    ///
+    /// @param fullPath [out] A string in which to return the composed path.
 
-    static void
-    ComposeLangSelector ( XMP_StringPtr      schemaNS,
-                          XMP_StringPtr      arrayName,
-                          const tStringObj & langName,
-                          tStringObj *       fullPath );
+    static void ComposeLangSelector ( XMP_StringPtr      schemaNS,
+									  XMP_StringPtr      arrayName,
+									  const tStringObj & langName,
+									  tStringObj *       fullPath );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Compose the path expression to select an alternate item by a field's value.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c ComposeFieldSelector() composes a path expression to select an alternate item by a field's value.
     ///
-    /// The path syntax allows two forms of "content addressing" that may be used to select an item
-    /// in an array of alternatives. The form used in \c ComposeFieldSelector lets you select an
-    /// item in an array of structs based on the value of one of the fields in the structs. The
-    /// other form of content addressing is shown in \c ComposeLangSelector.
+    /// Path syntax allows two forms of "content addressing" to select an item in an array of
+    /// alternatives. The form used in this function lets you select an item in an array of structs
+    /// based on the value of one of the fields in the structs. The other form of content addressing
+    /// is shown in \c ComposeLangSelector().
     ///
-    /// For example, consider a simple struct that has two fields, the name of a city and the URI
-    /// of an FTP site in that city. Use this to create an array of download alternatives. You can
-    /// show the user a popup built from the values of the city fields. You can then get the
-    /// corresponding URI as follows:
+    /// For example, consider a simple struct that has two fields, the name of a city and the URI of
+    /// an FTP site in that city. Use this to create an array of download alternatives. You can show
+    /// the user a popup built from the values of the city fields, then get the corresponding URI as
+    /// follows:
+    /// <pre>
+    ///   ComposeFieldSelector ( schemaNS, "Downloads", fieldNS, "City", chosenCity, &path );
+    ///   exists = GetStructField ( schemaNS, path, fieldNS, "URI", &uri );
+    /// </pre>
     ///
-    /// \verbatim
-    ///  ComposeFieldSelector ( schemaNS, "Downloads", fieldNS, "City", chosenCity, &path );
-    ///  exists = GetStructField ( schemaNS, path, fieldNS, "URI", &uri );
-    /// \endverbatim
+    /// The returned string is in the form <tt>ns:arrayName[fNS:fieldName='fieldValue']</tt>, where
+    /// "ns" is the prefix for the schema namespace and "fNS" is the prefix for the field namespace.
     ///
-    /// \param schemaNS The namespace URI for the array. Must not be null or the empty string.
+    /// @param schemaNS The namespace URI for the array; see \c GetProperty().
     ///
-    /// \param arrayName The name of the array. May be a general path expression, must not be null
-    /// or the empty string.
+    /// @param arrayName The name of the array. Can be a general path expression, must not be null
+    /// or the empty string; see \c GetProperty() for namespace prefix usage.
     ///
-    /// \param fieldNS The namespace URI for the field used as the selector. Must not be null or the
-    /// empty string.
+    /// @param fieldNS The namespace URI for the field used as the selector. Same URI and prefix
+    /// usage as the \c schemaNS and \c arrayName parameters.
     ///
-    /// \param fieldName The name of the field used as the selector. Must be a simple XML name, must
+    /// @param fieldName The name of the field used as the selector. Must be a single XML name, must
     /// not be null or the empty string. It must be the name of a field that is itself simple.
     ///
-    /// \param fieldValue The desired value of the field.
+    /// @param fieldValue The desired value of the field, specified as a null-terminated UTF-8 string.
     ///
-    /// \param fullPath A pointer to the string that will be assigned the composed path. This will
-    /// be of the form <tt>ns:arrayName[fNS:fieldName='fieldValue']</tt>, where "ns" is the prefix
-    /// for \c schemaNS and "fNS" is the prefix for \c fieldNS.
+    /// @param fullPath [out] A string in which to return the composed path.
 
-    static void
-    ComposeFieldSelector ( XMP_StringPtr schemaNS,
-                           XMP_StringPtr arrayName,
-                           XMP_StringPtr fieldNS,
-                           XMP_StringPtr fieldName,
-                           XMP_StringPtr fieldValue,
-                           tStringObj *  fullPath );
+    static void ComposeFieldSelector ( XMP_StringPtr schemaNS,
+									   XMP_StringPtr arrayName,
+									   XMP_StringPtr fieldNS,
+									   XMP_StringPtr fieldName,
+									   XMP_StringPtr fieldValue,
+									   tStringObj *  fullPath );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief This form of ComposeFieldSelector is a simple overload in the template that calls the
-    /// above form passing <tt>fieldValue.c_str()</tt>.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c ComposeFieldSelector() composes a path expression to select an alternate item by a field's value.
+    ///
+    /// Path syntax allows two forms of "content addressing" to select an item in an array of
+    /// alternatives. The form used in this function lets you select an item in an array of structs
+    /// based on the value of one of the fields in the structs. The other form of content addressing
+    /// is shown in \c ComposeLangSelector().
+    ///
+    /// For example, consider a simple struct that has two fields, the name of a city and the URI of
+    /// an FTP site in that city. Use this to create an array of download alternatives. You can show
+    /// the user a popup built from the values of the city fields, then get the corresponding URI as
+    /// follows:
+    /// <pre>
+    ///   ComposeFieldSelector ( schemaNS, "Downloads", fieldNS, "City", chosenCity, &path );
+    ///   exists = GetStructField ( schemaNS, path, fieldNS, "URI", &uri );
+    /// </pre>
+    ///
+    /// The returned string is in the form <tt>ns:arrayName[fNS:fieldName='fieldValue']</tt>, where
+    /// "ns" is the prefix for the schema namespace and "fNS" is the prefix for the field namespace.
+    ///
+    /// @param schemaNS The namespace URI for the array; see \c GetProperty().
+    ///
+    /// @param arrayName The name of the array. Can be a general path expression, must not be null
+    /// or the empty string; see \c GetProperty() for namespace prefix usage.
+    ///
+    /// @param fieldNS The namespace URI for the field used as the selector. Same URI and prefix
+    /// usage as the \c schemaNS and \c arrayName parameters.
+    ///
+    /// @param fieldName The name of the field used as the selector. Must be a single XML name, must
+    /// not be null or the empty string. It must be the name of a field that is itself simple.
+    ///
+    /// @param fieldValue The desired value of the field, specified as a string object.
+    ///
+    /// @param fullPath [out] A string in which to return the composed path.
 
-    static void
-    ComposeFieldSelector ( XMP_StringPtr      schemaNS,
-                           XMP_StringPtr      arrayName,
-                           XMP_StringPtr      fieldNS,
-                           XMP_StringPtr      fieldName,
-                           const tStringObj & fieldValue,
-                           tStringObj *       fullPath );
+    static void ComposeFieldSelector ( XMP_StringPtr      schemaNS,
+									   XMP_StringPtr      arrayName,
+									   XMP_StringPtr      fieldNS,
+									   XMP_StringPtr      fieldName,
+									   const tStringObj & fieldValue,
+									   tStringObj *       fullPath );
 
     /// @}
 
     // =============================================================================================
-    // =============================================================================================
-
-    //  ============================================================================================
-    /// \name Binary-String conversion functions
+    /// \name Conversion between binary types and strings
     /// @{
+    ///
+	///	The main accessors in \c TXMPMeta set and retrieve property values as strings. additional
+	///	functions, such as \c TXMPMeta::SetPropertyInt(), set and retrieve property values as
+	///	explicit binary data types. Use these functions to convert between binary and string
+	///	values.
+	///
+	///	Strings can be specified as null-terminated UTF-8 (\c #XMP_StringPtr), or as string
+	///	objects (\c tStringObj) of the type declared when instantiating the XMP classes; see
+	///	\c XMP.hpp. Alternate forms of each conversion function allow either type of string.
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Convert from Boolean to string.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c ConvertFromBool() converts a Boolean value to a string.
     ///
-    /// \param binValue The Boolean value to be converted.
+    /// The string values of Booleans are returned by the macros \c #kXMP_TrueStr and
+    /// \c #kXMP_FalseStr in \c XMP_Const.h.
     ///
-    /// \param strValue The string representation of the Boolean. The values used are given by the
-    /// macros \c kXMP_TrueStr and \c kXMP_FalseStr found in \c XMP_Const.h.
+    /// @param binValue The Boolean value to be converted.
+    ///
+    /// @param strValue [out] A buffer in which to return the string representation of the value.
 
-    static void
-    ConvertFromBool ( bool         binValue,
-                      tStringObj * strValue );
+    static void ConvertFromBool ( bool	       binValue,
+								  tStringObj * strValue );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Convert from integer to string.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c ConvertFromInt() converts a 32-bit integer value to a string.
     ///
-    /// \param binValue The integer value to be converted.
+    /// @param binValue The integer value to be converted.
     ///
-    /// \param format Optional C sprintf format for the conversion. Defaults to "%d".
+    /// @param format Optional. A C \c sprintf format for the conversion. Default is "%d".
     ///
-    /// \param strValue The string representation of the integer.
+    /// @param strValue [out] A buffer in which to return the string representation of the value.
 
-    static void
-    ConvertFromInt ( long          binValue,
-                     XMP_StringPtr format,
-                     tStringObj *  strValue );
+    static void ConvertFromInt ( long	       binValue,
+								 XMP_StringPtr format,
+								 tStringObj *  strValue );
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c ConvertFromInt64() converts a 64-bit integer value to a string.
+    ///
+    /// @param binValue The integer value to be converted.
+    ///
+    /// @param format Optional. A C \c sprintf format for the conversion. Default is "%d".
+    ///
+    /// @param strValue [out] A buffer in which to return the string representation of the value.
 
-    static void
-    ConvertFromInt64 ( long long     binValue,
-                       XMP_StringPtr format,
-                       tStringObj *  strValue );
+    static void ConvertFromInt64 ( long long	 binValue,
+								   XMP_StringPtr format,
+								   tStringObj *  strValue );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Convert from floating point to string.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c ConvertFromFloat() converts a floating-point value to a string.
     ///
-    /// \param binValue The floating point value to be converted.
+    /// @param binValue The floating-point value to be converted.
     ///
-    /// \param format Optional C sprintf format for the conversion. Defaults to "%f".
+    /// @param format Optional. A C \c sprintf format for the conversion. Default is "%d".
     ///
-    /// \param strValue The string representation of the floating point value.
+    /// @param strValue [out] A buffer in which to return the string representation of the value.
 
-    static void
-    ConvertFromFloat ( double        binValue,
-                       XMP_StringPtr format,
-                       tStringObj *  strValue );
+    static void ConvertFromFloat ( double	     binValue,
+								   XMP_StringPtr format,
+								   tStringObj *	 strValue );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Convert from date/time to string.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c ConvertFromDate() converts a date/time value to a string.
     ///
-    /// Format a date according to the ISO 8601 profile in http://www.w3.org/TR/NOTE-datetime:
-    ///	YYYY
-    ///	YYYY-MM
-    ///	YYYY-MM-DD
-    ///	YYYY-MM-DDThh:mmTZD
-    ///	YYYY-MM-DDThh:mm:ssTZD
-    ///	YYYY-MM-DDThh:mm:ss.sTZD
+    /// Formats a date according to the ISO 8601 profile in http://www.w3.org/TR/NOTE-datetime:
+    /// <pre>
+    ///   YYYY
+    ///   YYYY-MM
+    ///   YYYY-MM-DD
+    ///   YYYY-MM-DDThh:mmTZD
+    ///   YYYY-MM-DDThh:mm:ssTZD
+    ///   YYYY-MM-DDThh:mm:ss.sTZD
+    /// </pre>
     ///
-    ///	YYYY = four-digit year
-    ///	MM	 = two-digit month (01=January, etc.)
-    ///	DD	 = two-digit day of month (01 through 31)
-    ///	hh	 = two digits of hour (00 through 23)
-    ///	mm	 = two digits of minute (00 through 59)
-    ///	ss	 = two digits of second (00 through 59)
-    ///	s	 = one or more digits representing a decimal fraction of a second
-    ///	TZD	 = time zone designator (Z or +hh:mm or -hh:mm)
+    ///  \c YYYY = four-digit year, formatted as "%.4d" <br>
+    ///  \c MM	 = two-digit month (01=January)	<br>
+    ///  \c DD	 = two-digit day of month (01 through 31) <br>
+    ///  \c hh	 = two digits of hour (00 through 23) <br>
+    ///  \c mm	 = two digits of minute (00 through 59)	<br>
+    ///  \c ss	 = two digits of second (00 through 59)	<br>
+    ///  \c s	 = one or more digits representing a decimal fraction of a second <br>
+    ///  \c TZD	 = time zone designator (Z or +hh:mm or -hh:mm)
     ///
-    /// \note ISO 8601 does not seem to allow years less than 1000 or greater than 9999. We allow
-    /// any year, even negative ones. The year is formatted as "%.4d".
+    /// Time-only input is allowed where the year, month, and day are all zero. This is output as
+    /// "0000-00-00...".
     ///
-    /// \note As a compatibility "tactic" (OK, a hack), so-called time-only input is allowed where
-    /// the year, month, and day are all zero. This is output as "0000-00-00...".
+    /// @note ISO 8601 does not allow years less than 1000 or greater than 9999. This API allows
+    /// any year, even negative ones.
     ///
-    /// \param binValue The \c XMP_DateTime value to be converted.
+    /// @param binValue The date/time value to be converted.
     ///
-    /// \param strValue The ISO 8601 string representation of the date/time.
+    /// @param strValue [out] A buffer in which to return the ISO 8601 string representation of the date/time.
 
-    static void
-    ConvertFromDate ( const XMP_DateTime & binValue,
-                      tStringObj *         strValue );
+    static void ConvertFromDate ( const XMP_DateTime & binValue,
+								  tStringObj *	       strValue );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Convert from string to Boolean.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c ConvertToBool() converts a string to a Boolean value.
+    ///
+    /// The preferred strings are those returned by the macros \c #kXMP_TrueStr and \c #kXMP_FalseStr.
+    /// If these do not match, the function does a case insensitive comparison, then simply 't' or 'f',
+    /// and finally non-zero and zero integer representations.
     ///
-    /// \param strValue The string representation of the Boolean.
+    /// @param strValue The string representation of the value, specified as a null-terminated UTF-8 string.
     ///
-    /// \result The appropriate C++ bool value for the string. The preferred strings are
-    /// \c kXMP_TrueStr and \c kXMP_FalseStr. If these do not match, a case insensitive comparison is
-    /// tried, then simply 't' or 'f', and finally non-zero and zero integer representations.
+    /// @return The appropriate C++ bool value for the string.
 
-    static bool
-    ConvertToBool ( XMP_StringPtr strValue );
+    static bool ConvertToBool ( XMP_StringPtr strValue );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief This form of \c ConvertToBool is a simple overload in the template that calls the
-    /// above form passing <tt>strValue.c_str()</tt>.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c ConvertToBool() converts a string to a Boolean value.
+    ///
+    /// Overloads the basic form of the function, allowing you to pass a string object,
+	/// rather than a <tt>const * char</tt>. It is otherwise identical; see details in the canonical form.
+    ///
+    /// @param strValue The string representation of the value, specified as a string object.
+    ///
+    /// @return The appropriate C++ bool value for the string.
 
-    static bool
-    ConvertToBool ( const tStringObj & strValue );
+    static bool ConvertToBool ( const tStringObj & strValue );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Convert from string to integer.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c ConvertToInt() converts a string to a 32-bit integer value.
     ///
-    /// \param strValue The string representation of the integer.
+    /// @param strValue The string representation of the value, specified as a null-terminated UTF-8 string.
     ///
-    /// \result The integer value as a C long.
+    /// @return The 32-bit integer value.
 
-    static long
-    ConvertToInt ( XMP_StringPtr strValue );
+    static long ConvertToInt ( XMP_StringPtr strValue );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief This form of \c ConvertToInt is a simple overload in the template that calls the above
-    /// form passing <tt>strValue.c_str()</tt>.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c ConvertToInt() converts a string to a 32-bit integer value.
+    ///
+    /// Overloads the basic form of the function, allowing you to pass a string object,
+	/// rather than a <tt>const * char</tt>. It is otherwise identical.
+	///
+    /// @param strValue The string representation of the value, specified as a string object.
+    ///
+    /// @return The 32-bit integer value.
 
-    static long
-    ConvertToInt ( const tStringObj & strValue );
+    static long ConvertToInt ( const tStringObj & strValue );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Convert from string to 64 bit integer.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c ConvertToInt64() converts a string to a 64-bit integer value.
     ///
-    /// \param strValue The string representation of the integer.
+    /// @param strValue The string representation of the value, specified as a null-terminated UTF-8 string.
     ///
-    /// \result The integer value as a C long long.
+    /// @return The 64-bit integer value.
 
-    static long long
-    ConvertToInt64 ( XMP_StringPtr strValue );
+    static long long ConvertToInt64 ( XMP_StringPtr strValue );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief This form of ConvertToInt64 is a simple overload in the template that calls the above
-    /// form passing <tt>strValue.c_str()</tt>.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c ConvertToInt64() converts a string to a 64-bit integer value.
+    ///
+    /// Overloads the basic form of the function, allowing you to pass a string object,
+	/// rather than a <tt>const * char</tt>. It is otherwise identical.
+	///
+    /// @param strValue The string representation of the value, specified as a string object.
+    ///
+    /// @return The 64-bit integer value.
 
-    static long long
-    ConvertToInt64 ( const tStringObj & strValue );
+    static long long ConvertToInt64 ( const tStringObj & strValue );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Convert from string to floating point.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c ConvertToFloat() converts a string to a floating-point value.
     ///
-    /// \param strValue The string representation of the floating point value.
+    /// @param strValue The string representation of the value, specified as a null-terminated UTF-8 string.
     ///
-    /// \result The floating point value.
+    /// @return The floating-point value.
 
-    static double
-    ConvertToFloat ( XMP_StringPtr strValue );
+    static double ConvertToFloat ( XMP_StringPtr strValue );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief This form of \c ConvertToFloat is a simple overload in the template that calls the
-    /// above form passing <tt>strValue.c_str()</tt>.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c ConvertToFloat() converts a string to a floating-point value.
+    ///
+    /// Overloads the basic form of the function, allowing you to pass a string object,
+	/// rather than a <tt>const * char</tt>. It is otherwise identical.
+	///
+    /// @param strValue The string representation of the value, specified as a string object.
+    ///
+    /// @return The floating-point value.
 
-    static double
-    ConvertToFloat ( const tStringObj & strValue );
+    static double ConvertToFloat ( const tStringObj & strValue );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Convert from string to date/time.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c ConvertToDate() converts a string to a date/time value.
     ///
-    /// Parse a date according to the ISO 8601 profile in http://www.w3.org/TR/NOTE-datetime:
-    ///	YYYY
-    ///	YYYY-MM
-    ///	YYYY-MM-DD
-    ///	YYYY-MM-DDThh:mmTZD
-    ///	YYYY-MM-DDThh:mm:ssTZD
-    ///	YYYY-MM-DDThh:mm:ss.sTZD
+    /// Parses a date according to the ISO 8601 profile in http://www.w3.org/TR/NOTE-datetime:
+    /// <pre>
+    ///   YYYY
+    ///   YYYY-MM
+    ///   YYYY-MM-DD
+    ///   YYYY-MM-DDThh:mmTZD
+    ///   YYYY-MM-DDThh:mm:ssTZD
+    ///   YYYY-MM-DDThh:mm:ss.sTZD
+    /// </pre>
     ///
-    ///	YYYY = four-digit year
-    ///	MM	 = two-digit month (01=January, etc.)
-    ///	DD	 = two-digit day of month (01 through 31)
-    ///	hh	 = two digits of hour (00 through 23)
-    ///	mm	 = two digits of minute (00 through 59)
-    ///	ss	 = two digits of second (00 through 59)
-    ///	s	 = one or more digits representing a decimal fraction of a second
-    ///	TZD	 = time zone designator (Z or +hh:mm or -hh:mm)
+    ///  \c YYYY = four-digit year, formatted as "%.4d" <br>
+    ///  \c MM	 = two-digit month (01=January)	<br>
+    ///  \c DD	 = two-digit day of month (01 through 31) <br>
+    ///  \c hh	 = two digits of hour (00 through 23) <br>
+    ///  \c mm	 = two digits of minute (00 through 59)	<br>
+    ///  \c ss	 = two digits of second (00 through 59)	<br>
+    ///  \c s	 = one or more digits representing a decimal fraction of a second <br>
+    ///  \c TZD	 = time zone designator (Z or +hh:mm or -hh:mm)
     ///
-    /// \note ISO 8601 does not seem to allow years less than 1000 or greater than 9999. We allow
-    /// any year, even negative ones. The year is assumed to be formatted as "%.4d".
+    /// A missing date portion or missing TZD are tolerated. A missing date value can begin with
+    /// "Thh:" or "hh:"; the year, month, and day are all set to zero in the \c #XMP_DateTime value.
+    /// A missing TZD is assumed to be UTC.
     ///
-    /// \note As compatibility "tactics" (OK, hacks), a missing date portion or missing TZD are
-    /// tolerated. A missing date value may begin with "Thh:" or "hh:"; the year, month, and day are
-    /// all set to zero in the XMP_DateTime value. A missing TZD is assumed to be UTC.
+    /// @note ISO 8601 does not allow years less than 1000 or greater than 9999. This API allows
+    /// any year, even negative ones.
     ///
-    /// \param strValue The ISO 8601 string representation of the date/time.
+    /// @param strValue The ISO 8601 string representation of the date/time, specified as a
+    /// null-terminated UTF-8 string.
     ///
-    /// \param binValue A pointer to the \c XMP_DateTime variable to be assigned the date/time components.
+    /// @param binValue [out] A buffer in which to return the binary date/time value.
 
-    static void
-    ConvertToDate ( XMP_StringPtr  strValue,
-                    XMP_DateTime * binValue );
+    static void ConvertToDate ( XMP_StringPtr  strValue,
+								XMP_DateTime * binValue );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief This form of \c ConvertToDate is a simple overload in the template that calls the above
-    /// form passing s<tt>strValue.c_str()</tt>.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c ConvertToDate() converts a string to a date/time value.
+    ///
+    /// Overloads the basic form of the function, allowing you to pass a string object,
+	/// rather than a <tt>const * char</tt>. It is otherwise identical.
+	/// See details for the canonical form.
+	///
+    ///
+    /// @param strValue The ISO 8601 string representation of the date/time, specified as a string
+    /// object.
+    ///
+    /// @param binValue [out] A buffer in which to return the binary date/time value.
 
-    static void
-    ConvertToDate ( const tStringObj & strValue,
-                    XMP_DateTime *     binValue );
+    static void ConvertToDate ( const tStringObj & strValue,
+								XMP_DateTime *     binValue );
 
     /// @}
 
     // =============================================================================================
-    // =============================================================================================
-
-    //  ============================================================================================
-    /// \name Date/Time functions
+    /// \name Date-time manipulation
     /// @{
+    ///
+	///	In addition to the type-conversion functions that convert between strings and binary
+	///	date-time values, these functions create, manipulate, and compare date-time values.
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Obtain the current date and time.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c CurrentDateTime() obtains the current date and time.
+    ///
+    /// Creates and returns a binary \c #XMP_DateTime value. The returned time is UTC, properly
+    /// adjusted for the local time zone. The resolution of the time is not guaranteed to be finer
+    /// than seconds.
     ///
-    /// \param time	A pointer to the \c XMP_DateTime variable to be assigned the current date
-    /// and time. The returned time is UTC, properly adjusted for the local time zone. The
-    /// resolution of the time is not guaranteed to be finer than seconds.
+    /// @param time	[out] A buffer in which to return the date/time value.
 
-    static void
-    CurrentDateTime ( XMP_DateTime * time );
+    static void CurrentDateTime ( XMP_DateTime * time );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Set the local time zone.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c SetTimeZone() sets the time zone in a date/time value to the local time zone.
+    ///
+    /// Any existing time zone value is replaced. The other date/time fields are not adjusted in any way.
     ///
-    /// \param time	A pointer to the \c XMP_DateTime variable containing the value to be modified. Any
-    /// existing time zone value is replaced, the other date/time fields are not adjusted in any way.
+    /// @param time	A pointer to the date-time value, which is modified in place.
 
-    static void
-    SetTimeZone ( XMP_DateTime * time );
+    static void SetTimeZone ( XMP_DateTime * time );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Make sure a time is UTC.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c ConvertToUTCTime() ensures that a time is UTC.
     ///
-    /// \param time	A pointer to the \c XMP_DateTime variable containing the time to be modified. If
-    /// the time zone is not UTC, the time is adjusted and the time zone set to be UTC.
+    /// If the time zone is not UTC, the time is adjusted and the time zone set to be UTC. If the
+    /// time zone is already UTC, the value is not modified.
+    ///
+    /// @param time	A pointer to the date-time value, which is modified in place.
 
-    static void
-    ConvertToUTCTime ( XMP_DateTime * time );
+    static void ConvertToUTCTime ( XMP_DateTime * time );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Make sure a time is local.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c ConvertToLocalTime() ensures that a time is local.
+    ///
+    /// If the time zone is not the local zone, the time is adjusted and the time zone set to be local.
+    /// If the time zone is already the local zone, the value is not modified.
     ///
-    /// \param time	A pointer to the \c XMP_DateTime variable containing the time to be modified. If
-    /// the time zone is not the local zone, the time is adjusted and the time zone set to be local.
+    /// @param time	A pointer to the date-time value, which is modified in place.
 
-    static void
-    ConvertToLocalTime ( XMP_DateTime * time );
+    static void ConvertToLocalTime ( XMP_DateTime * time );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Compare the order of two date/time values.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c CompareDateTime() compares the order of two date/time values.
     ///
-    /// \param left The "lefthand" date/time.
+    /// @param left The left-side date/time value.
     ///
-    /// \param right The "righthand" date/time.
+    /// @param right The right-side date/time value.
     ///
-    /// \result
-    /// \li -1 if left is before right
-    /// \li 0 if left matches right
-    /// \li +1 if left is after right
+    /// @return An integer indicating the order:
+    ///   \li -1 if left is earlier than right
+    ///   \li 0 if left matches right
+    ///   \li +1 if left is later than right
 
-    static int
-    CompareDateTime ( const XMP_DateTime & left,
-                      const XMP_DateTime & right );
+    static int CompareDateTime ( const XMP_DateTime & left,
+								 const XMP_DateTime & right );
 
     /// @}
 
     // =============================================================================================
-    // =============================================================================================
-
-    //  ============================================================================================
-    /// \name Base 64 Encoding and Decoding
+    /// \name Base64 encoding and decoding
     /// @{
+    ///
+	/// These functions convert between raw data values and Base64-encoded strings.
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Convert from raw data to Base64 encoded string.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c EncodeToBase64() converts a raw data value to a Base64-encoded string.
     ///
-    /// \param rawStr The pointer to raw data to be converted.
+    /// @param rawStr An \c #XMP_StringPtr (char *) string containing the raw data to be converted.
     ///
-    /// \param rawLen The length of raw data to be converted.
+    /// @param rawLen The number of characters of raw data to be converted.
     ///
-    /// \param encodedStr The XMP object to contain the encoded string.
+    /// @param encodedStr [out] A string object in which to return the encoded string.
 
-    static void
-    EncodeToBase64 ( XMP_StringPtr rawStr,
-                     XMP_StringLen rawLen,
-                     tStringObj *  encodedStr );
+    static void EncodeToBase64 ( XMP_StringPtr rawStr,
+								 XMP_StringLen rawLen,
+								 tStringObj *  encodedStr );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief This form of \c EncodeToBase64 is a simple overload in the template that calls the
-    /// above form passing <tt>rawStr.c_str()</tt>, and <tt>rawStr.size()</tt>.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c EncodeToBase64() converts a raw data value passed in a string object to a Base64-encoded string.
+    ///
+    /// Overloads the basic form of the function, allowing you to pass a string object as input.
+	/// It is otherwise identical.
+ 	///
+    /// @param rawStr A string object containing the raw data to be converted.
+    ///
+    /// @param encodedStr [out] A string object in which to return the encoded string.
 
-    static void
-    EncodeToBase64 ( const tStringObj & rawStr,
-                     tStringObj *       encodedStr );
+    static void  EncodeToBase64 ( const tStringObj & rawStr,
+								  tStringObj *       encodedStr );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Decode from Base64 encoded string to raw data.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c  DecodeFromBase64() Decodes a Base64-encoded string to raw data.
     ///
-    /// \param encodedStr The pointer to encoded data to be converted.
+    /// @param encodedStr An \c #XMP_StringPtr (char *) string containing the encoded data to be converted.
     ///
-    /// \param encodedLen The length of encoded datavto be converted.
+    /// @param encodedLen The number of characters of raw data to be converted.
     ///
-    /// \param rawStr The XMP object to contain the decoded string.
+    /// @param rawStr [out] A string object in which to return the decoded data.
 
-    static void
-    DecodeFromBase64 ( XMP_StringPtr encodedStr,
-                       XMP_StringLen encodedLen,
-                       tStringObj *  rawStr );
+    static void DecodeFromBase64 ( XMP_StringPtr encodedStr,
+								   XMP_StringLen encodedLen,
+								   tStringObj *  rawStr );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief This form of \c DecodeFromBase64 is a simple overload in the template that calls the
-    /// above form passing <tt>encodedStr.c_str()</tt>, and <tt>encodedStr.size()</tt>.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c  DecodeFromBase64() Decodes a Base64-encoded string, passed as a string object, to raw data.
+    ///
+    /// Overloads the basic form of the function, allowing you to pass a string object as input.
+	/// It is otherwise identical.
+ 	///
+    /// @param encodedStr An string object containing the encoded data to be converted.
+    ///
+    /// @param rawStr [out] A string object in which to return the decoded data.
 
-    static void
-    DecodeFromBase64 ( const tStringObj & encodedStr,
-                       tStringObj *       rawStr );
+    static void DecodeFromBase64 ( const tStringObj & encodedStr,
+								   tStringObj *       rawStr );
 
     /// @}
 
     // =============================================================================================
     // =============================================================================================
-
-    //  ============================================================================================
     /// \name JPEG file handling
     /// @{
-    /// These functions support the partitioning of XMP in JPEG files into standard and extended 
+    ///
+    /// These functions support the partitioning of XMP in JPEG files into standard and extended
     /// portions in order to work around the 64KB size limit of JPEG marker segments.
+    ///
+	/// @note (Doc note) Add detail about how to write out and read back extended data
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Create XMP serializations appropriate for a JPEG file. The standard XMP in a JPEG
-    /// file is limited to about 65500 bytes. \c PackageForJPEG attempts to fit the serialization
-    /// within that limit. If necessary it will partition the XMP into 2 serializations.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c PackageForJPEG() creates XMP serializations appropriate for a JPEG file.
     ///
-    /// \param xmpObj The XMP for the JPEG file.
+    /// The standard XMP in a JPEG file is limited to 64K bytes. This function serializes the XMP
+    /// metadata in an XMP object into a string of RDF (see \c TXMPMeta::SerializeToBuffer()). If
+    /// the data does not fit into the 64K byte limit, it creates a second packet string with the
+    /// extended data.
     ///
-    /// \param standardXMP The full standard XMP packet.
+    /// @param xmpObj The XMP object containing the metadata.
     ///
-    /// \param extendedXMP The serialized extended XMP, empty if not needed.
+    /// @param standardXMP [out] A string object in which to return the full standard XMP packet.
     ///
-    /// \param extendedDigest An MD5 digest of the serialized extended XMP, empty if not needed.
+    /// @param extendedXMP [out] A string object in which to return the serialized extended XMP,
+    /// empty if not needed.
+    ///
+    /// @param extendedDigest [out] A string object in which to return an MD5 digest of the serialized
+    /// extended XMP, empty if not needed.
+    ///
+    /// @see \c MergeFromJPEG()
 
-    static void
-    PackageForJPEG ( const TXMPMeta<tStringObj> & xmpObj,
-                     tStringObj * standardXMP,
-                     tStringObj * extendedXMP,
-                     tStringObj * extendedDigest );
+    static void PackageForJPEG ( const TXMPMeta<tStringObj> & xmpObj,
+								 tStringObj *                 standardXMP,
+								 tStringObj *                 extendedXMP,
+								 tStringObj *                 extendedDigest );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Put the extended XMP properties back into the full XMP.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c MergeFromJPEG() merges standard and extended XMP retrieved from a JPEG file.
+    ///
+    /// When an extended partition stores properties that do not fit into the JPEG file limitation
+    /// of 64K bytes, this function integrates those properties back into the same XMP object with
+    /// those from the standard XMP packet.
     ///
-    /// \param fullXMP The full XMP, presumed to be initialized from the standard XMP packet.
+    /// @param fullXMP [in, out] An XMP object which the caller has initialized from the standard
+    /// XMP packet in a JPEG file. The extended XMP is added to this object.
     ///
-    /// \param extendedXMP The properties that were partitioned into the extended XMP.
+    /// @param extendedXMP An XMP object which the caller has initialized from the extended XMP
+    /// packet in a JPEG file.
+    ///
+    /// @see \c PackageForJPEG()
 
-    static void
-    MergeFromJPEG ( TXMPMeta<tStringObj> * fullXMP,
-                    const TXMPMeta<tStringObj> & extendedXMP );
+    static void MergeFromJPEG ( TXMPMeta<tStringObj> *       fullXMP,
+								const TXMPMeta<tStringObj> & extendedXMP );
 
     /// @}
 
     // =============================================================================================
-    // =============================================================================================
-
-    //  ============================================================================================
-    /// \name UI helper functions
+    /// \name Editing utilities
     /// @{
-    /// These functions are mainly of interest in implementing a user interface for editing XMP.
+    ///
+    /// These functions are useful in implementing a user interface for editing XMP. They
+	/// convert sets of property values to and from displayable and manipulable strings, and perform
+	/// operations on sets of metadata, such as those available from the File Info dialog box.
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Create a single edit string from an array of strings.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c CatenateArrayItems() creates a single edit string from a set of array item values.
     ///
-    /// TBD - needs more description
+    /// Collects the values of all items in an array into a single string, using a specified
+    /// separation string. Each item in the specified array must be a simple string value.
     ///
-    /// \param xmpObj The XMP object containing the array to be catenated.
+    /// @param xmpObj The XMP object containing the array to be catenated.
     ///
-    /// \param schemaNS The schema namespace URI for the array. Must not be null or the empty string.
+    /// @param schemaNS The schema namespace URI for the array. Must not be null or the empty string.
     ///
-    /// \param arrayName The name of the array. May be a general path expression, must not be null
-    /// or the empty string. Each item in the array must be a simple string value.
+    /// @param arrayName The name of the array. May be a general path expression, must not be null
+    /// or the empty string.
     ///
-    /// \param separator The string to be used to separate the items in the catenated string.
+    /// @param separator The string with which to separate the items in the catenated string.
     /// Defaults to "; ", ASCII semicolon and space (U+003B, U+0020).
     ///
-    /// \param quotes The characters to be used as quotes around array items that contain a separator.
-    /// Defaults to '"', ASCII quote (U+0022).
+    /// @param quotes The character or characters to use as quotes around array items that contain a
+    /// separator. Defaults to the double-quote character ("), ASCII quote (U+0022).
+    ///
+    /// @param options Option flags to control the catenation. <<what options?>>
     ///
-    /// \param options Option flags to control the catenation.
+    /// @param catedStr [out] A string object in which to return the catenated array items.
     ///
-    /// \param catedStr A pointer to the string to be assigned the catenated array items.
+    /// @see \c SeparateArrayItems()
 
-    static void
-    CatenateArrayItems ( const TXMPMeta<tStringObj> & xmpObj,
-                         XMP_StringPtr  schemaNS,
-                         XMP_StringPtr  arrayName,
-                         XMP_StringPtr  separator,
-                         XMP_StringPtr  quotes,
-                         XMP_OptionBits options,
-                         tStringObj *   catedStr );
+    static void CatenateArrayItems ( const TXMPMeta<tStringObj> & xmpObj,
+									 XMP_StringPtr                schemaNS,
+									 XMP_StringPtr                arrayName,
+									 XMP_StringPtr                separator,
+									 XMP_StringPtr                quotes,
+									 XMP_OptionBits               options,
+									 tStringObj *                 catedStr );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Separate a single edit string into an array of strings.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c SeparateArrayItems() updates an array from a concatenated edit string of values.
     ///
-    /// TBD - needs more description
+    /// This reverses the action of \c CatenateArrayItems(), separating out individual array items
+    /// from the edit string and updating the array with the new values. Each item in the array must
+    /// be a simple string value.
     ///
-    /// \param xmpObj The XMP object containing the array to be updated.
+    /// @param xmpObj The XMP object containing the array to be updated.
     ///
-    /// \param schemaNS The schema namespace URI for the array. Must not be null or the empty string.
+    /// @param schemaNS The schema namespace URI for the array. Must not be null or the empty string.
     ///
-    /// \param arrayName The name of the array. May be a general path expression, must not be null
-    /// or the empty string. Each item in the array must be a simple string value.
+    /// @param arrayName The name of the array. May be a general path expression, must not be null
+    /// or the empty string.
     ///
-    /// \param options Option flags to control the separation.
+    /// @param options Option flags to control the separation. <<what options?>>
     ///
-    /// \param catedStr The string to be separated into the array items.
+    /// @param catedStr The concatenated array items, as created by \c CatenateArrayItems(),
+    /// specified as a null-terminated UTF-8 string.
 
-    static void
-    SeparateArrayItems ( TXMPMeta<tStringObj> * xmpObj,
-                         XMP_StringPtr  schemaNS,
-                         XMP_StringPtr  arrayName,
-                         XMP_OptionBits options,
-                         XMP_StringPtr  catedStr );
+    static void SeparateArrayItems ( TXMPMeta<tStringObj> * xmpObj,
+									 XMP_StringPtr          schemaNS,
+									 XMP_StringPtr          arrayName,
+									 XMP_OptionBits         options,
+									 XMP_StringPtr          catedStr );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief This form of \c SeparateArrayItems is a simple overload in the template that calls
-    /// the aboveform passing <tt>catedStr.c_str()</tt>.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c SeparateArrayItems() updates an array from a concatenated edit string of values.
+    ///
+    /// Overloads the basic form of the function, allowing you to pass a string object in which
+    ///	to return the concatenated string. It is otherwise identical; see details for the canonical form.
+ 	///
 
-    static void
-    SeparateArrayItems ( TXMPMeta<tStringObj> * xmpObj,
-                         XMP_StringPtr      schemaNS,
-                         XMP_StringPtr      arrayName,
-                         XMP_OptionBits     options,
-                         const tStringObj & catedStr );
+    static void SeparateArrayItems ( TXMPMeta<tStringObj> * xmpObj,
+									 XMP_StringPtr          schemaNS,
+									 XMP_StringPtr          arrayName,
+									 XMP_OptionBits         options,
+									 const tStringObj &     catedStr );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Remove multiple properties from an XMP object.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c  RemoveProperties() removes multiple properties from an XMP object.
     ///
-    /// \c RemoveProperties was created to support the File Info dialog's Delete button, and has
-    /// been been generalized somewhat from those specific needs. It operates in one of three main
-    /// modes depending on the schemaNS and propName parameters:
+    /// The operation depends on how the namespace and property are specified:
     ///
-    /// \li Non-empty \c schemaNS and \c propName - The named property is removed if it is an
-    /// external property, or if the \c kXMPUtil_DoAllProperties option is passed. It does not
-    /// matter whether the named property is an actual property or an alias.
+    ///   \li Non-empty \c schemaNS and \c propName - The named property is removed if it is an
+    ///   external property, or if the \c #kXMPUtil_DoAllProperties option flag is set. It does not
+    ///   matter whether the named property is an actual property or an alias.
     ///
-    /// \li Non-empty \c schemaNS and empty \c propName - The all external properties in the named
-    /// schema are removed. Internal properties are also removed if the \c kXMPUtil_DoAllProperties
-    /// option is passed. In addition, aliases from the named schema will be removed if the \c
-    /// kXMPUtil_IncludeAliases option is passed.
+    ///   \li Non-empty \c schemaNS and empty \c propName - All external properties in the named
+    ///   schema are removed. Internal properties are also removed if the
+    ///   \c #kXMPUtil_DoAllProperties option flag is set. In addition, aliases from the named schema
+    ///   are removed if the \c #kXMPUtil_IncludeAliases option flag is set.
     ///
-    /// \li Empty \c schemaNS and empty \c propName - All external properties in all schema are
-    /// removed. Internal properties are also removed if the \c kXMPUtil_DoAllProperties option is
-    /// passed. Aliases are implicitly handled because the associated actuals are.
+    ///   \li Empty \c schemaNS and empty \c propName - All external properties in all schemas are
+    ///   removed. Internal properties are also removed if the \c #kXMPUtil_DoAllProperties option
+    ///   flag is set. Aliases are handled implicitly, because the associated actuals are removed or
+    ///   not.
     ///
-    /// It is an error to pass and empty schemaNS and non-empty propName.
+    ///   \li It is an error to pass an empty \c schemaNS and non-empty \c propName.
     ///
-    /// \param xmpObj The XMP object containing the properties to be removed.
+    /// @param xmpObj The XMP object containing the properties to be removed.
     ///
-    /// \param schemaNS Optional schema namespace URI for the properties to be removed.
+    /// @param schemaNS Optional schema namespace URI for the properties to be removed.
     ///
-    /// \param propName Optional path expression for the property to be removed.
+    /// @param propName Optional path expression for the property to be removed.
     ///
-    /// \param options Option flags to control the deletion. The defined flags are:
-    /// \li \c kXMPUtil_DoAllProperties - Do internal properties in addition to external properties.
-    /// \li \c kXMPUtil_IncludeAliases - Include aliases in the "named schema" case above.
+    /// @param options Option flags to control the deletion operation. A logical OR of these
+    /// bit-flag constants:
+    ///   \li \c #kXMPUtil_DoAllProperties - Delete internal properties in addition to external properties.
+    ///   \li \c #kXMPUtil_IncludeAliases - Include aliases if the schema is explicitly specified.
 
-    static void
-    RemoveProperties ( TXMPMeta<tStringObj> * xmpObj,
-                       XMP_StringPtr  schemaNS = 0,
-                       XMP_StringPtr  propName = 0,
-                       XMP_OptionBits options = 0 );
+    static void RemoveProperties ( TXMPMeta<tStringObj> * xmpObj,
+								   XMP_StringPtr          schemaNS = 0,
+								   XMP_StringPtr          propName = 0,
+								   XMP_OptionBits         options = 0 );
 
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Append properties from one XMP object to another.
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c AppendProperties() adds or moves properties from one XMP object to another.
     ///
-    /// \c AppendProperties was created to support the File Info dialog's Append button, and has
-    /// been been generalized somewhat from those specific needs. It appends information from one
-    /// XMP object (\c source) to another (\c dest). The default operation is to append only external
-    /// properties that do not already exist in the destination. The kXMPUtil_DoAllProperties option
-    /// can be used to operate on all properties, external and internal. The kXMPUtil_ReplaceOldValues
-    /// option can be used to replace the values of existing properties. The notion of external
-    /// versus internal applies only to top level properties. The keep-or-replace-old notion applies
-    /// within structs and arrays as described below.
+    /// The default operation is to append only external properties that do not already exist in the
+    /// destination. Option flags allow you to	add internal properties, and to merge values of
+    /// properties that exist in both the source and destination.
     ///
-    /// If kXMPUtil_ReplaceOldValues is passed then the processing is restricted to the top level
-    /// properties. The processed properties from the source (according to kXMPUtil_DoAllProperties)
-    /// are propagated to the destination, replacing any existing values. Properties in the destination
-    /// that are not in the source are left alone.
+    ///   \li \c #kXMPUtil_DoAllProperties: Operate on all top-level properties, external and
+    ///   internal. You can use this flag together with \c #kXMPUtil_ReplaceOldValues to replace the
+    ///   values of existing top-level properties.
     ///
-    /// If kXMPUtil_ReplaceOldValues is not passed then the processing is more complicated. Top level
-    /// properties are added to the destination if they do not already exist. If they do exist but
-    /// differ in form (simple/struct/array) then the destination is left alone. If the forms match,
-    /// simple properties are left unchanged while structs and arrays are merged.
+    ///   \li \c #kXMPUtil_ReplaceOldValues: Propogate all top-level properties from the source to
+    ///   the destination, replacing any existing values. The values of properties in the
+    ///   destination that are not in the source are not modified.<br>
+    ///   The keep-or-replace-old notion also applies within structs and arrays. Top-level
+    ///   properties are added to the destination if they do not already exist. If they do exist but
+    ///   differ in form (simple/struct/array) then the destination is not modified. If the forms
+    ///   match, simple properties are left unchanged, while structs and arrays are merged.<br>
+    ///   Do not use this option when the processing is more complicated. <<than what??>>
     ///
-    /// If kXMPUtil_DeleteEmptyValues is passed then an empty value in the source XMP causes the
-    /// corresponding Dest XMP property to be deleted. The default is to treat empty values the same
-    /// as non-empty values. An empty value is any of a simple empty string, an array with no items,
-    /// or a struct with no fields. Qualifiers are ignored.
+    ///   \li \c #kXMPUtil_DeleteEmptyValues: An empty value in the source XMP causes the
+    ///   corresponding destination property to be deleted. By default, empty values are treated in
+    ///   the same way as non-empty values. An empty value is a simple empty string, an array with
+    ///   no items,or a struct with no fields. Qualifiers are ignored.
     ///
     /// The detailed behavior is defined by the following pseudo-code:
-    /// \verbatim
-    ///   AppendProperties ( sourceXMP, destXMP, options ):
-    ///      doAll = options & kXMPUtil_DoAllProperties
-    ///      replaceOld = options & kXMPUtil_ReplaceOldValues
-    ///      deleteEmpty = options & kXMPUtil_DeleteEmptyValues
-    ///      for all source schema (top level namespaces):
-    ///         for all top level properties in sourceSchema:
-    ///            if doAll or prop is external:
-    ///               AppendSubtree ( sourceNode, destSchema, replaceOld, deleteEmpty )
-    ///
-    ///   AppendSubtree ( sourceNode, destParent, replaceOld, deleteEmpty ):
-    ///      if deleteEmpty and source value is empty:
-    ///         delete the corresponding child from destParent
-    ///      else if sourceNode not in destParent (by name):
-    ///         copy sourceNode's subtree to destParent
-    ///      else if replaceOld:
-    ///         delete subtree from destParent
-    ///         copy sourceNode's subtree to destParent
-    ///      else:
-    ///         // Already exists in dest and not replacing, merge structs and arrays
-    ///         if sourceNode and destNode forms differ:
-    ///            return, leave the destNode alone
-    ///         else if form is a struct:
-    ///            for each field in sourceNode:
-    ///               AppendSubtree ( sourceNode.field, destNode, replaceOld )
-    ///         else if form is an alt-text array:
-    ///            copy new items by xml:lang value into the destination
-    ///         else if form is an array:
-    ///            copy new items by value into the destination, ignoring order and duplicates
-    /// \endverbatim
-    ///
-    /// \note \c AppendProperties can be expensive if replaceOld is not passed and the XMP contains
-    /// large arrays. The array item checking described above is n-squared. Each source item is
-    /// checked to see if it already exists in the destination, without regard to order or duplicates.
-    /// Simple items are compared by value and xml:lang qualifier, other qualifiers are ignored.
-    /// Structs are recursively compared by field names, without regard to field order. Arrays are
-    /// compared by recursively comparing all items.
-    ///
-    /// \param source The source XMP object.
-    ///
-    /// \param dest The destination XMP object.
-    ///
-    /// \param options Option flags to control the copying.
-    /// \li \c kXMPUtil_DoAllProperties - Do internal properties in addition to external properties.
-    /// \li \c kXMPUtil_ReplaceOldValues - Replace the values of existing properties.
-    /// \li \c kXMPUtil_DeleteEmptyValues - Delete properties if the new value is empty.
-
-    static void
-    AppendProperties ( const TXMPMeta<tStringObj> & source,
-                       TXMPMeta<tStringObj> *       dest,
-                       XMP_OptionBits options = 0 );
-
-    //  --------------------------------------------------------------------------------------------
-    /// \brief Replicate a subtree from one XMP object into another, possibly at a different location.
-    ///
-    /// TBD - needs more description
-    ///
-    /// \param source The source XMP object.
-    ///
-    /// \param dest The destination XMP object.
-    ///
-    /// \param sourceNS The schema namespace URI for the source subtree.
-    ///
-    /// \param sourceRoot The root location for the source subtree. May be a general path expression,
+    ///
+    /// <pre>
+    /// AppendProperties ( sourceXMP, destXMP, options ):
+    ///    doAll = options & kXMPUtil_DoAllProperties
+    ///    replaceOld = options & kXMPUtil_ReplaceOldValues
+    ///    deleteEmpty = options & kXMPUtil_DeleteEmptyValues
+    ///    for all source schema (top level namespaces):
+    ///    for all top level properties in sourceSchema:
+    ///    if doAll or prop is external:
+    ///       AppendSubtree ( sourceNode, destSchema, replaceOld, deleteEmpty )
+    ///
+    /// AppendSubtree ( sourceNode, destParent, replaceOld, deleteEmpty ):
+    ///    if deleteEmpty and source value is empty:
+    ///       delete the corresponding child from destParent
+    ///    else if sourceNode not in destParent (by name):
+    ///       copy sourceNode's subtree to destParent
+    ///    else if replaceOld:
+    ///       delete subtree from destParent
+    ///       copy sourceNode's subtree to destParent
+    ///    else: // (Already exists in dest and not replacing, merge structs and arrays)
+    ///       if sourceNode and destNode forms differ:
+    ///          return, leave the destNode alone
+    ///       else if form is a struct:
+    ///          for each field in sourceNode:
+    ///             AppendSubtree ( sourceNode.field, destNode, replaceOld )
+    ///       else if form is an alt-text array:
+    ///          copy new items by xml:lang value into the destination
+    ///       else if form is an array:
+    ///          copy new items by value into the destination, ignoring order and duplicates
+    /// </pre>
+    ///
+    /// Array item checking is n-squared; this can be time-intensive if the replace-old options is
+    /// not specified. Each source item is checked to see if it already exists in the destination,
+    /// without regard to order or duplicates. Simple items are compared by value and \c xml:lang
+    /// qualifier; other qualifiers are ignored. Structs are recursively compared by field names,
+    /// without regard to field order. Arrays are compared by recursively comparing all items.
+    ///
+    /// @param source The source XMP object.
+    ///
+    /// @param dest The destination XMP object.
+    ///
+    /// @param options Option flags to control the copying.	A logical OR of these bit-flag constants:
+    ///   \li \c kXMPUtil_DoAllProperties - Operate on internal properties in addition to external properties.
+    ///   \li \c kXMPUtil_ReplaceOldValues - Replace the values of existing properties.
+    ///   \li \c kXMPUtil_DeleteEmptyValues - Delete properties if the new value is empty.
+
+    static void AppendProperties ( const TXMPMeta<tStringObj> & source,
+								   TXMPMeta<tStringObj> *       dest,
+								   XMP_OptionBits               options = 0 );
+
+    // ---------------------------------------------------------------------------------------------
+    /// @brief \c DuplicateSubtree() replicates a subtree from one XMP object into another.
+    ///
+    /// The destination can be a different namespace and root location in the same object, or the
+    /// same or a different location in another XMP object.
+    ///
+    /// @param source The source XMP object.
+    ///
+    /// @param dest The destination XMP object.
+    ///
+    /// @param sourceNS The schema namespace URI for the source subtree.
+    ///
+    /// @param sourceRoot The root location for the source subtree. Can be a general path expression,
     /// must not be null or the empty string.
     ///
-    /// \param destNS The schema namespace URI for the destination. Defaults to the source namespace.
+    /// @param destNS The schema namespace URI for the destination. Defaults to the source namespace.
     ///
-    /// \param destRoot The root location for the destination. May be a general path expression.
+    /// @param destRoot The root location for the destination. Can be a general path expression.
     /// Defaults to the source location.
     ///
-    /// \param options Option flags to control the separation.
-
-    static void
-    DuplicateSubtree ( const TXMPMeta<tStringObj> & source,
-                       TXMPMeta<tStringObj> *       dest,
-                       XMP_StringPtr  sourceNS,
-                       XMP_StringPtr  sourceRoot,
-                       XMP_StringPtr  destNS = 0,
-                       XMP_StringPtr  destRoot = 0,
-                       XMP_OptionBits options = 0 );
+    /// @param options Option flags to control the operation. <<options?>>
 
+    static void DuplicateSubtree ( const TXMPMeta<tStringObj> & source,
+								   TXMPMeta<tStringObj> *       dest,
+								   XMP_StringPtr                sourceNS,
+								   XMP_StringPtr                sourceRoot,
+								   XMP_StringPtr                destNS = 0,
+								   XMP_StringPtr                destRoot = 0,
+								   XMP_OptionBits               options = 0 );
 
     /// @}
 
     // =============================================================================================
 
+    // =============================================================================================
+
 };  // class TXMPUtils
 
 // =================================================================================================
diff --git a/public/include/XMP.hpp b/public/include/XMP.hpp
index 2ceb936..62e230d 100644
--- a/public/include/XMP.hpp
+++ b/public/include/XMP.hpp
@@ -11,16 +11,16 @@
 
 //  ================================================================================================
 /// \file XMP.hpp
-/// \brief Overall header file for the XMP toolkit.
+/// \brief Overall header file for the XMP Toolkit
 ///
-/// This is an overall header file, the only one that C++ clients should #include. The full client
-/// API is in the \c TXMPMeta.hpp, \c TXMPIterator.hpp, \c TXMPUtils.hpp headers. Read these for
-/// information, but do not #include them directly. The \c TXMP... classes are C++ template classes
-/// that must be instantiated with a string class such as <tt>std::string<\tt>. The string class is
-/// used to return text strings for property values, serialized XMP, etc. 
+/// This is an overall header file, the only one that C++ clients should include.
 ///
-/// Clients must also compile <tt>XMP.incl_cpp<\tt> to ensure that all client-side glue code is
-/// generated. This should be done by #including it in exactly one client source file.
+/// The full client API is in the \c TXMPMeta.hpp, \c TXMPIterator.hpp, \c TXMPUtils.hpp headers.
+/// Read these for information, but do not include them directly. The \c TXMP... classes are C++
+/// template classes that must be instantiated with a string class such as \c std::string. The
+/// string class is used to return text strings for property values, serialized XMP, and so on.
+/// Clients must also compile \c XMP.incl_cpp to ensure that all client-side glue code is generated.
+/// This should be done by including it in exactly one client source file.
 ///
 /// There are two C preprocessor macros that simplify use of the templates:
 ///
@@ -29,24 +29,27 @@
 ///
 /// \li \c TXMP_EXPAND_INLINE - Define this as 1 if you want to have the template functions expanded
 /// inline in your code. Leave it undefined, or defined as 0, to use out-of-line instantiations of
-/// the template functions. Compiling <tt>XMP.incl_cpp<\tt> generates explicit out-of-line
+/// the template functions. Compiling \c XMP.incl_cpp generates explicit out-of-line
 /// instantiations if \c TXMP_EXPAND_INLINE is off.
 ///
-/// The template parameter, class \c tStringObj, must have the following member functions (which match
-/// those for <tt>std::string<\tt>):
-/// \code
+/// The template parameter, class \c tStringObj, must have the following member functions (which
+/// match those for \c std::string):
+///
+/// <pre>
 ///  tStringObj& assign ( const char * str, size_t len )
 ///  size_t size() const
 ///  const char * c_str() const
-/// \endcode
+/// </pre>
+///
 /// The string class must be suitable for at least UTF-8. This is the encoding used for all general
 /// values, and is the default encoding for serialized XMP. The string type must also be suitable
 /// for UTF-16 or UTF-32 if those serialization encodings are used. This mainly means tolerating
-/// embedded 0 bytes, which std::string does.
+/// embedded 0 bytes, which \c std::string does.
 //  ================================================================================================
 
+/// /c XMP_Environment.h must be the first included header.
+#include "XMP_Environment.h"
 
-#include "XMP_Environment.h" // ! This must be the first include!
 #include "XMP_Version.h"
 #include "XMP_Const.h"
 
@@ -65,11 +68,9 @@
     #include "TXMPMeta.hpp"
     #include "TXMPIterator.hpp"
     #include "TXMPUtils.hpp"
-
     typedef class TXMPMeta <TXMP_STRING_TYPE>     SXMPMeta;       // For client convenience.
     typedef class TXMPIterator <TXMP_STRING_TYPE> SXMPIterator;
     typedef class TXMPUtils <TXMP_STRING_TYPE>    SXMPUtils;
-
     #if TXMP_EXPAND_INLINE
     	#error "TXMP_EXPAND_INLINE is not working at present. Please don't use it."
         #include "client-glue/TXMPMeta.incl_cpp"
@@ -92,7 +93,6 @@
     #pragma warning ( pop )
 #endif
 
-
 // =================================================================================================
 
 #endif  // __XMP_hpp__
diff --git a/public/include/XMP.incl_cpp b/public/include/XMP.incl_cpp
index 19b4b5f..79655be 100644
--- a/public/include/XMP.incl_cpp
+++ b/public/include/XMP.incl_cpp
@@ -50,11 +50,9 @@
     #include "client-glue/TXMPMeta.incl_cpp"
     #include "client-glue/TXMPIterator.incl_cpp"
     #include "client-glue/TXMPUtils.incl_cpp"
-
     template class TXMPMeta <TXMP_STRING_TYPE>;
     template class TXMPIterator <TXMP_STRING_TYPE>;
     template class TXMPUtils <TXMP_STRING_TYPE>;
-
 	#if XMP_INCLUDE_XMPFILES
 	    #include "client-glue/TXMPFiles.incl_cpp"
 	    template class TXMPFiles <TXMP_STRING_TYPE>;
diff --git a/public/include/XMP_Const.h b/public/include/XMP_Const.h
index 57605bd..0316188 100644
--- a/public/include/XMP_Const.h
+++ b/public/include/XMP_Const.h
@@ -1,25 +1,19 @@
 #ifndef __XMP_Const_h__
 #define __XMP_Const_h__ 1
 
-/* --------------------------------------------------------------------------------------------- */
-/* ** IMPORTANT ** This file must be usable by strict ANSI C compilers. No "//" comments, etc.   */
-/* --------------------------------------------------------------------------------------------- */
-
-/*
 // =================================================================================================
-// Copyright 2002-2007 Adobe Systems Incorporated
+// Copyright 2002-2008 Adobe Systems Incorporated
 // All Rights Reserved.
 //
 // NOTICE:  Adobe permits you to use, modify, and distribute this file in accordance with the terms
 // of the Adobe license agreement accompanying it.
 // =================================================================================================
-*/
 
 #include "XMP_Environment.h"
 
    #include <stddef.h>
 
-#if XMP_MacBuild	/* ! No stdint.h on Windows and some UNIXes. */
+#if XMP_MacBuild	// ! No stdint.h on Windows and some UNIXes.
     #include <stdint.h>
 #endif
 
@@ -27,20 +21,18 @@
 extern "C" {
 #endif
 
+// =================================================================================================
+/// \file XMP_Const.h
+/// \brief Common C/C++ types and constants for the XMP toolkit.
+// =================================================================================================
 
-/** ================================================================================================
- *  \file XMP_Const.h
- *  \brief Common C/C++ types and constants for the XMP toolkit.
- */
-
-
-/* ============================================================================================== */
-/* Basic types and constants */
-/* ========================= */
+// =================================================================================================
+// Basic types and constants
+// =========================
 
-/* The XMP_... types are used on the off chance that the ..._t types present a problem. In that */
-/* case only the declarations of the XMP_... types needs to change, not all of the uses. These  */
-/* types are used where fixed sizes are required in order to have a known ABI for a DLL build.  */
+// The XMP_... types are used on the off chance that the ..._t types present a problem. In that
+// case only the declarations of the XMP_... types needs to change, not all of the uses. These
+// types are used where fixed sizes are required in order to have a known ABI for a DLL build.
 
 #if XMP_MacBuild
 
@@ -70,205 +62,183 @@ extern "C" {
 
 typedef XMP_Uns8 XMP_Bool;
 
-/* Typedefs to preserve old, unfortunate spellings: */
-
-#if 0 /* *** Enable after internal compiles work. */
-typedef XMP_Int8  XMPInt8;
-typedef XMP_Int16 XMPInt16;
-typedef XMP_Int32 XMPInt32;
-typedef XMP_Int64 XMPInt64;
-typedef XMP_Uns8  XMPUns8;
-typedef XMP_Uns16 XMPUns16;
-typedef XMP_Uns32 XMPUns32;
-typedef XMP_Uns64 XMPUns64;
-typedef XMP_Bool  XMPBool;
-#endif
-
-/**
- *  \typedef XMPMetaRef
- *  \brief An "ABI safe" pointer to the internal part of an XMP object.
- *
- *  \c XMPMetaRef is an "ABI safe" pointer to the internal part of an XMP object. It should be used
- *  for passing an XMP object across client DLL boundaries. See the discussion in <tt>TXMPMeta.hpp</tt>.
- */
-
+/// An "ABI safe" pointer to the internal part of an XMP object. Use to pass an XMP object across
+/// client DLL boundaries. See \c TXMPMeta::GetInternalRef().
 typedef struct __XMPMeta__ *        XMPMetaRef;
+
+/// An "ABI safe" pointer to the internal part of an XMP iteration object. Use to pass an XMP
+/// iteration object across client DLL boundaries. See \c TXMPIterator.
 typedef struct __XMPIterator__ *    XMPIteratorRef;
+
+/// An "ABI safe" pointer to the internal part of an XMP document operations object. Use to pass an
+/// XMP document operations object across client DLL boundaries. See \c TXMPDocOps.
+typedef struct __XMPDocOps__ *    XMPDocOpsRef;
+
+/// An "ABI safe" pointer to the internal part of an XMP file-handling object. Use to pass an XMP
+/// file-handling object across  client DLL boundaries. See \c TXMPFiles.
 typedef struct __XMPFiles__ *       XMPFilesRef;
 
-/* ============================================================================================== */
-
-/**
- *  \name General scalar types and constants
- *  @{
- */
-
-/**
- *  \typedef XMP_StringPtr
- *  \brief The type for input string parameters. A <tt>const char *</tt>, a null-terminated UTF-8 string.
- *
- */
-
-/**
- *  \typedef XMP_StringLen
- *  \brief The type for string length parameters. A 32-bit unsigned integer, as big as will be
- *   practically needed.
- */
-
-/**
- *  \typedef XMP_Index
- *  \brief The type for offsets and indices. A 32-bit signed integer. It is signed because that
- *  often makes loop termination tests safer.
- */
-
-/**
- *  \typedef XMP_OptionBits
- *  \brief The type for a collection of 32 flag bits. Individual flags are defined as enum value
- *  bit masks. A number of macros provide common set or set operations, e.g. \c XMP_PropIsSimple.
- *  For other tests use an expression like "options & kXMP_<theOption>". When passing multiple
- *  option flags use the bitwise-or operator. '|', not the arithmatic plus, '+'.
- */
-
-typedef const char * XMP_StringPtr;  /* Points to a null terminated UTF-8 string. */
+// =================================================================================================
+
+/// \name General scalar types and constants
+/// @{
+
+/// \typedef XMP_StringPtr
+/// \brief The type for input string parameters. A <tt>const char *</tt>, a null-terminated UTF-8
+/// string.
+
+/// \typedef XMP_StringLen
+/// \brief The type for string length parameters. A 32-bit unsigned integer, as big as will be
+/// practically needed.
+
+/// \typedef XMP_Index
+/// \brief The type for offsets and indices. A 32-bit signed integer. It is signed to allow -1 for
+/// loop termination.
+
+/// \typedef XMP_OptionBits
+/// \brief The type for a collection of 32 flag bits. Individual flags are defined as enum value bit
+/// masks; see \c #kXMP_PropValueIsURI and following. A number of macros provide common set or set
+/// operations, such as \c XMP_PropIsSimple. For other tests use an expression like <code>options &
+/// kXMP_<theOption></code>. When passing multiple option flags use the bitwise-OR operator. '|',
+/// not the arithmatic plus, '+'.
+
+typedef const char * XMP_StringPtr;  // Points to a null terminated UTF-8 string.
 typedef XMP_Uns32    XMP_StringLen;
-typedef XMP_Int32    XMP_Index;      /* Signed, sometimes -1 is handy. */
-typedef XMP_Uns32    XMP_OptionBits; /* Used as 32 individual bits. */
-
-/**
- *  \def kXMP_TrueStr
- *  \brief The canonical true string value for Booleans in serialized XMP. Code that converts
- *  from the string to a bool should be case insensitive, and even allow "1".
- */
-
-/**
- *  \def kXMP_FalseStr
- *  \brief The canonical false string value for Booleans in serialized XMP. Code that converts
- *  from the string to a bool should be case insensitive, and even allow "0".
- */
-
-#define kXMP_TrueStr  "True"  /* Serialized XMP spellings, not for the type bool. */
+typedef XMP_Int32    XMP_Index;      // Signed, sometimes -1 is handy.
+typedef XMP_Uns32    XMP_OptionBits; // Used as 32 individual bits.
+
+/// \def kXMP_TrueStr
+/// \brief The canonical true string value for Booleans in serialized XMP.
+///
+/// Code that converts from string to bool should be case insensitive, and also allow "1".
+
+/// \def kXMP_FalseStr
+/// \brief The canonical false string value for Booleans in serialized XMP.
+///
+/// Code that converts	from string to bool should be case insensitive, and also allow "0".
+
+#define kXMP_TrueStr  "True"  // Serialized XMP spellings, not for the type bool.
 #define kXMP_FalseStr "False"
 
-/**
- *  @}
- */
-
-/* ============================================================================================== */
-
-/**
- *  \struct XMP_DateTime
- *  \brief The expanded type for a date and time. Dates and time in the serialized XMP are ISO 8601
- *   strings. The \c XMP_DateTime struct allows easy conversion with other formats.
- *
- *  All of the fields are 32 bit, even though most could be 8 bit. This avoids overflow when doing
- *  carries for arithmetic or normalization. All fields have signed values for the same reasons.
- *
- *  The fields of the \c XMP_DateTime struct are:
- *
- *  \li year- The year, can be negative.
- *  \li month - The month in the range 1..12.
- *  \li day - The day of the month in the range 1..31.
- *  \li hour - The hour in the range 0..23.
- *  \li minute - The minute in the range 0..59.
- *  \li second - The second in the range 0..59.
- *  \li tzSign - The "sign" of the time zone, 0 means UTC, -1 is west, +1 is east.
- *  \li tzHour - The time zone hour in the range 0..23.
- *  \li tzMinute - The time zone minute in the range 0..59.
- *  \li nanoSecond - Nanoseconds within a second, often left as zero.
- *
- *  Constants for the \c tzSign are:
- *
- *  \li \c kXMP_TimeIsUTC - The time is UTC.
- *  \li \c kXMP_TimeWestOfUTC - The time zone is west of UTC, behind in time.
- *  \li \c kXMP_TimeEastOfUTC - The time zone is east of UTC, ahead in time.
- *
- *  DateTime values are occasionally used in cases with only a date or only a time component. A date
- *  without a time has zeros in the \c XMP_DateTime struct for all time fields. A time without a date
- *  has zeros for all date fields (year, month, and day).
- */
+/// Type for yes/no/maybe answers. The values are picked to allow Boolean-like usage. The yes and
+/// values are true (non-zero), the no value is false (zero).
+enum {
+	/// The part or parts have definitely changed.
+	kXMPTS_Yes = 1,
+	/// The part or parts have definitely not changed.
+	kXMPTS_No = 0,
+	/// The part or parts might, or might not, have changed.
+	kXMPTS_Maybe = -1
+};
+typedef XMP_Int8 XMP_TriState;
+
+/// @}
+
+// =================================================================================================
+
+/// \struct XMP_DateTime
+/// \brief The expanded type for a date and time.
+///
+/// Dates and time in the serialized XMP are ISO 8601 strings. The \c XMP_DateTime struct allows
+/// easy conversion with other formats.
+///
+/// All of the fields are 32 bit, even though most could be 8 bit. This avoids overflow when doing
+/// carries for arithmetic or normalization. All fields have signed values for the same reasons.
+///
+/// Date-time values are occasionally used with only a date or only a time component. A date without
+/// a time has zeros in the \c XMP_DateTime struct for all time fields. A time without a date has
+/// zeros for all date fields (year, month, and day).
+///
+/// \c TXMPUtils provides utility functions for manipulating date-time values.
+///
+/// @see \c TXMPUtils::ConvertToDate(), \c TXMPUtils::ConvertFromDate(),
+/// \c TXMPUtils::CompareDateTime(), \c TXMPUtils::ConvertToLocalTime(),
+/// \c TXMPUtils::ConvertToUTCTime(), \c TXMPUtils::CurrentDateTime(),
+/// \c TXMPUtils::SetTimeZone()
 
 struct XMP_DateTime {
+
+	/// The year, can be negative.
     XMP_Int32 year;
-    XMP_Int32 month;      /* 1..12 */
-    XMP_Int32 day;        /* 1..31 */
-    XMP_Int32 hour;       /* 0..23 */
-    XMP_Int32 minute;     /* 0..59 */
-    XMP_Int32 second;     /* 0..59 */
-    XMP_Int32 tzSign;     /* -1..+1, 0 means UTC, -1 is west, +1 is east. */
-    XMP_Int32 tzHour;     /* 0..23 */
-    XMP_Int32 tzMinute;   /* 0..59 */
+
+	/// The month in the range 1..12.
+    XMP_Int32 month;
+
+	/// The day of the month in the range 1..31.
+    XMP_Int32 day;
+
+	/// The hour in the range 0..23.
+    XMP_Int32 hour;
+
+	/// The minute in the range 0..59.
+    XMP_Int32 minute;
+
+	/// The second in the range 0..59.
+    XMP_Int32 second;
+
+	/// The "sign" of the time zone, \c #kXMP_TimeIsUTC (0) means UTC, \c #kXMP_TimeWestOfUTC (-1)
+	/// is west, \c #kXMP_TimeEastOfUTC (+1) is east.
+    XMP_Int32 tzSign;
+
+	/// The time zone hour in the range 0..23.
+    XMP_Int32 tzHour;
+
+	/// The time zone minute in the range 0..59.
+    XMP_Int32 tzMinute;
+
+	/// Nanoseconds within a second, often left as zero.
     XMP_Int32 nanoSecond;
+
 };
 
-enum {  /* Values used for tzSign field. */
+/// Constant values for \c XMP_DateTime::tzSign field.
+enum {
+	/// Time zone is west of UTC.
     kXMP_TimeWestOfUTC = -1,
+	/// UTC time.
     kXMP_TimeIsUTC     =  0,
+	/// Time zone is east of UTC.
     kXMP_TimeEastOfUTC = +1
 };
 
-
-/* ============================================================================================== */
-/* Standard namespace URI constants */
-/* ================================ */
-
-/**
- *  \name XML namespace constants for standard XMP schema.
- *  @{
- */
-
-/**
- *  \def kXMP_NS_XMP
- *  \brief The XML namespace for the XMP "basic" schema.
- */
-
-/**
- *  \def kXMP_NS_XMP_Rights
- *  \brief The XML namespace for the XMP copyright schema.
- */
-
-/**
- *  \def kXMP_NS_XMP_MM
- *  \brief The XML namespace for the XMP digital asset management schema.
- */
-
-/**
- *  \def kXMP_NS_XMP_BJ
- *  \brief The XML namespace for the job management schema.
- */
-
-/**
- *  \def kXMP_NS_XMP_T
- *  \brief The XML namespace for the XMP text document schema.
- */
-
-/**
- *  \def kXMP_NS_XMP_T_PG
- *  \brief The XML namespace for the XMP paged document schema.
- */
-
-/**
- *  \def kXMP_NS_PDF
- *  \brief The XML namespace for the PDF schema.
- */
-
-/**
- *  \def kXMP_NS_Photoshop
- *  \brief The XML namespace for the Photoshop custom schema.
- */
-
-/**
- *  \def kXMP_NS_EXIF
- *  \brief The XML namespace for Adobe's EXIF schema.
- */
-
-/**
- *  \def kXMP_NS_TIFF
- *  \brief The XML namespace for Adobe's TIFF schema.
- */
-
-/**
- *  @}
- */
+// =================================================================================================
+// Standard namespace URI constants
+// ================================
+
+/// \name XML namespace constants for standard XMP schema.
+/// @{
+///
+/// \def kXMP_NS_XMP
+/// \brief The XML namespace for the XMP "basic" schema.
+///
+/// \def kXMP_NS_XMP_Rights
+/// \brief The XML namespace for the XMP copyright schema.
+///
+/// \def kXMP_NS_XMP_MM
+/// \brief The XML namespace for the XMP digital asset management schema.
+///
+/// \def kXMP_NS_XMP_BJ
+/// \brief The XML namespace for the job management schema.
+///
+/// \def kXMP_NS_XMP_T
+/// \brief The XML namespace for the XMP text document schema.
+///
+/// \def kXMP_NS_XMP_T_PG
+/// \brief The XML namespace for the XMP paged document schema.
+///
+/// \def kXMP_NS_PDF
+/// \brief The XML namespace for the PDF schema.
+///
+/// \def kXMP_NS_Photoshop
+/// \brief The XML namespace for the Photoshop custom schema.
+///
+/// \def kXMP_NS_EXIF
+/// \brief The XML namespace for Adobe's EXIF schema.
+///
+/// \def kXMP_NS_TIFF
+/// \brief The XML namespace for Adobe's TIFF schema.
+///
+/// @}
 
 #define kXMP_NS_XMP        "http://ns.adobe.com/xap/1.0/"
 
@@ -294,50 +264,33 @@ enum {  /* Values used for tzSign field. */
 #define kXMP_NS_XMP_Note   "http://ns.adobe.com/xmp/note/"
 
 #define kXMP_NS_AdobeStockPhoto "http://ns.adobe.com/StockPhoto/1.0/"
-
-/**
- *  \name XML namespace constants for qualifiers and structured property fields.
- *  @{
- */
-
-/**
- *  \def kXMP_NS_XMP_IdentifierQual
- *  \brief The XML namespace for qualifiers of the xmp:Identifier property.
- */
-
-/**
- *  \def kXMP_NS_XMP_Dimensions
- *  \brief The XML namespace for fields of the Dimensions type.
- */
-
-/**
- *  \def kXMP_NS_XMP_Image
- *  \brief The XML namespace for fields of a graphical image. Used for the Thumbnail type.
- */
-
-/**
- *  \def kXMP_NS_XMP_ResourceEvent
- *  \brief The XML namespace for fields of the ResourceEvent type.
- */
-
-/**
- *  \def kXMP_NS_XMP_ResourceRef
- *  \brief The XML namespace for fields of the ResourceRef type.
- */
-
-/**
- *  \def kXMP_NS_XMP_ST_Version
- *  \brief The XML namespace for fields of the Version type.
- */
-
-/**
- *  \def kXMP_NS_XMP_ST_Job
- *  \brief The XML namespace for fields of the JobRef type.
- */
-
-/**
- *  @}
- */
+#define kXMP_NS_CreatorAtom "http://ns.adobe.com/creatorAtom/1.0/"
+
+/// \name XML namespace constants for qualifiers and structured property fields.
+/// @{
+///
+/// \def kXMP_NS_XMP_IdentifierQual
+/// \brief The XML namespace for qualifiers of the xmp:Identifier property.
+///
+/// \def kXMP_NS_XMP_Dimensions
+/// \brief The XML namespace for fields of the Dimensions type.
+///
+/// \def kXMP_NS_XMP_Image
+/// \brief The XML namespace for fields of a graphical image. Used for the Thumbnail type.
+///
+/// \def kXMP_NS_XMP_ResourceEvent
+/// \brief The XML namespace for fields of the ResourceEvent type.
+///
+/// \def kXMP_NS_XMP_ResourceRef
+/// \brief The XML namespace for fields of the ResourceRef type.
+///
+/// \def kXMP_NS_XMP_ST_Version
+/// \brief The XML namespace for fields of the Version type.
+///
+/// \def kXMP_NS_XMP_ST_Job
+/// \brief The XML namespace for fields of the JobRef type.
+///
+/// @}
 
 #define kXMP_NS_XMP_IdentifierQual "http://ns.adobe.com/xmp/Identifier/qual/1.0/"
 #define kXMP_NS_XMP_Dimensions     "http://ns.adobe.com/xap/1.0/sType/Dimensions#"
@@ -352,43 +305,33 @@ enum {  /* Values used for tzSign field. */
 #define kXMP_NS_XMP_ST_Job         "http://ns.adobe.com/xap/1.0/sType/Job#"
 #define kXMP_NS_XMP_ManifestItem   "http://ns.adobe.com/xap/1.0/sType/ManifestItem#"
 
-/* Deprecated constant names */
+// Deprecated XML namespace constants
 #define kXMP_NS_XMP_T     "http://ns.adobe.com/xap/1.0/t/"
 #define kXMP_NS_XMP_T_PG  "http://ns.adobe.com/xap/1.0/t/pg/"
 #define kXMP_NS_XMP_G_IMG "http://ns.adobe.com/xap/1.0/g/img/"
 
-/**
- *  \name XML namespace constants from outside Adobe.
- *  @{
- */
-
-/**
- *  \def kXMP_NS_DC
- *  \brief The XML namespace for the Dublin Core schema.
- */
-
-/**
- *  \def kXMP_NS_IPTCCore
- *  \brief The XML namespace for the IPTC Core schema.
- */
-
-/**
- *  \def kXMP_NS_RDF
- *  \brief The XML namespace for RDF.
- */
-
-/**
- *  \def kXMP_NS_XML
- *  \brief The XML namespace for XML.
- */
-
-/**
- *  @}
- */
-
-#define kXMP_NS_DC       "http://purl.org/dc/elements/1.1/"
-
-#define kXMP_NS_IPTCCore "http://iptc.org/std/Iptc4xmpCore/1.0/xmlns/"
+/// \name XML namespace constants from outside Adobe.
+/// @{
+///
+/// \def kXMP_NS_DC
+/// \brief The XML namespace for the Dublin Core schema.
+///
+/// \def kXMP_NS_IPTCCore
+/// \brief The XML namespace for the IPTC Core schema.
+///
+/// \def kXMP_NS_RDF
+/// \brief The XML namespace for RDF.
+///
+/// \def kXMP_NS_XML
+/// \brief The XML namespace for XML.
+///
+/// @}
+
+#define kXMP_NS_DC              "http://purl.org/dc/elements/1.1/"
+
+#define kXMP_NS_IPTCCore       "http://iptc.org/std/Iptc4xmpCore/1.0/xmlns/"
+
+#define kXMP_NS_DICOM          "http://ns.adobe.com/DICOM/"
 
 #define kXMP_NS_PDFA_Schema    "http://www.aiim.org/pdfa/ns/schema#"
 #define kXMP_NS_PDFA_Property  "http://www.aiim.org/pdfa/ns/property#"
@@ -400,28 +343,127 @@ enum {  /* Values used for tzSign field. */
 #define kXMP_NS_PDFX           "http://ns.adobe.com/pdfx/1.3/"
 #define	kXMP_NS_PDFX_ID        "http://www.npes.org/pdfx/ns/id/"
 
-#define kXMP_NS_RDF      "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
-#define kXMP_NS_XML      "http://www.w3.org/XML/1998/namespace"
-
+#define kXMP_NS_RDF            "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+#define kXMP_NS_XML            "http://www.w3.org/XML/1998/namespace"
 
-/* ============================================================================================== */
-/* Enums and macros used for option bits */
-/* ===================================== */
+// =================================================================================================
+// Enums and macros used for option bits
+// =====================================
+
+/// \name Macros for standard option selections.
+/// @{
+///
+/// \def kXMP_ArrayLastItem
+/// \brief Options macro accesses last array item.
+///
+/// \def kXMP_UseNullTermination
+/// \brief Options macro sets string style.
+///
+/// \def kXMP_NoOptions
+/// \brief Options macro clears all property-type bits.
+///
+/// @}
 
 #define kXMP_ArrayLastItem      ((XMP_Index)(-1L))
 #define kXMP_UseNullTermination ((XMP_StringLen)(~0UL))
-
 #define kXMP_NoOptions          ((XMP_OptionBits)0UL)
 
+/// \name Macros for setting and testing general option bits.
+/// @{
+///
+/// \def XMP_SetOption
+/// \brief Macro sets an option flag bit.
+///	\param var A variable storing an options flag.
+/// \param opt The bit-flag constant to set.
+///
+/// \def XMP_ClearOption
+/// \brief Macro clears an option flag bit.
+///	\param var A variable storing an options flag.
+/// \param opt The bit-flag constant to clear.
+///
+/// \def XMP_TestOption
+/// \brief Macro reports whether an option flag bit is set.
+///	\param var A variable storing an options flag.
+/// \param opt The bit-flag constant to test.
+/// \return True if the bit is set.
+///
+/// \def XMP_OptionIsSet
+/// \brief Macro reports whether an option flag bit is set.
+///	\param var A variable storing an options flag.
+/// \param opt The bit-flag constant to test.
+/// \return True if the bit is set.
+///
+/// \def XMP_OptionIsClear
+/// \brief Macro reports whether an option flag bit is clear.
+///	\param var A variable storing an options flag.
+/// \param opt The bit-flag constant to test.
+/// \return True if the bit is clear.
+///
+/// @}
+
 #define XMP_SetOption(var,opt)      var |= (opt)
 #define XMP_ClearOption(var,opt)    var &= ~(opt)
 #define XMP_TestOption(var,opt)     (((var) & (opt)) != 0)
 #define XMP_OptionIsSet(var,opt)    (((var) & (opt)) != 0)
 #define XMP_OptionIsClear(var,opt)  (((var) & (opt)) == 0)
 
+/// \name Macros for setting and testing specific option bits.
+/// @{
+///
+/// \def XMP_PropIsSimple
+/// \brief Macro reports the property type specified by an options flag.
+/// \param opt The options flag to check.
+///
+/// \def XMP_PropIsStruct
+/// \brief Macro reports the property type specified by an options flag.
+/// \param opt The options flag to check.
+///
+/// \def XMP_PropIsArray
+/// \brief Macro reports the property type specified by an options flag.
+/// \param opt The options flag to check.
+///
+/// \def XMP_ArrayIsUnordered
+/// \brief Macro reports the property type specified by an options flag.
+/// \param opt The options flag to check.
+///
+/// \def XMP_ArrayIsOrdered
+/// \brief Macro reports the property type specified by an options flag.
+/// \param opt The options flag to check.
+///
+/// \def XMP_ArrayIsAlternate
+/// \brief Macro reports the property type specified by an options flag.
+/// \param opt The options flag to check.
+///
+/// \def XMP_ArrayIsAltText
+/// \brief Macro reports the property type specified by an options flag.
+/// \param opt The options flag to check.
+///
+/// \def XMP_PropHasQualifiers
+/// \brief Macro reports the property type specified by an options flag.
+/// \param opt The options flag to check.
+///
+/// \def XMP_PropIsQualifier
+/// \brief Macro reports the property type specified by an options flag.
+/// \param opt The options flag to check.
+///
+/// \def XMP_PropHasLang
+/// \brief Macro reports the property type specified by an options flag.
+/// \param opt The options flag to check.
+///
+/// \def XMP_NodeIsSchema
+/// \brief Macro reports the property type specified by an options flag.
+/// \param opt The options flag to check.
+///
+/// \def XMP_PropIsAlias
+/// \brief Macro reports the property type specified by an options flag.
+/// \param opt The options flag to check.
+///
+/// @}
+
 #define XMP_PropIsSimple(opt)       (((opt) & kXMP_PropCompositeMask) == 0)
 #define XMP_PropIsStruct(opt)       (((opt) & kXMP_PropValueIsStruct) != 0)
 #define XMP_PropIsArray(opt)        (((opt) & kXMP_PropValueIsArray) != 0)
+
 #define XMP_ArrayIsUnordered(opt)   (((opt) & kXMP_PropArrayIsOrdered) == 0)
 #define XMP_ArrayIsOrdered(opt)     (((opt) & kXMP_PropArrayIsOrdered) != 0)
 #define XMP_ArrayIsAlternate(opt)   (((opt) & kXMP_PropArrayIsAlternate) != 0)
@@ -434,480 +476,855 @@ enum {  /* Values used for tzSign field. */
 #define XMP_NodeIsSchema(opt)       (((opt) & kXMP_SchemaNode) != 0)
 #define XMP_PropIsAlias(opt)        (((opt) & kXMP_PropIsAlias) != 0)
 
-/* ---------------------------------------------------------------------------------------------- */
-
-enum {  /* Option bits returned from the TXMPMeta::GetXyz functions. */
-
-    /* Options relating to the XML string form of the property value. */
-    kXMP_PropValueIsURI       = 0x00000002UL,  /* The value is a URI, use rdf:resource attribute. DISCOURAGED */
-
-    /* Options relating to qualifiers attached to a property. */
-    kXMP_PropHasQualifiers    = 0x00000010UL,  /* The property has qualifiers, includes rdf:type and xml:lang. */
-    kXMP_PropIsQualifier      = 0x00000020UL,  /* This is a qualifier, includes rdf:type and xml:lang. */
-    kXMP_PropHasLang          = 0x00000040UL,  /* Implies kXMP_PropHasQualifiers, property has xml:lang. */
-    kXMP_PropHasType          = 0x00000080UL,  /* Implies kXMP_PropHasQualifiers, property has rdf:type. */
-
-    /* Options relating to the data structure form. */
-    kXMP_PropValueIsStruct    = 0x00000100UL,  /* The value is a structure with nested fields. */
-    kXMP_PropValueIsArray     = 0x00000200UL,  /* The value is an array (RDF alt/bag/seq). */
-    kXMP_PropArrayIsUnordered = kXMP_PropValueIsArray,  /* The item order does not matter. */
-    kXMP_PropArrayIsOrdered   = 0x00000400UL,  /* Implies kXMP_PropValueIsArray, item order matters. */
-    kXMP_PropArrayIsAlternate = 0x00000800UL,  /* Implies kXMP_PropArrayIsOrdered, items are alternates. */
-
-    /* Additional struct and array options. */
-    kXMP_PropArrayIsAltText   = 0x00001000UL,  /* Implies kXMP_PropArrayIsAlternate, items are localized text. */
-    /* kXMP_InsertBeforeItem  = 0x00004000UL,  ! Used by SetXyz functions. */
-    /* kXMP_InsertAfterItem   = 0x00008000UL,  ! Used by SetXyz functions. */
-
-    /* Other miscellaneous options. */
-    kXMP_PropIsAlias          = 0x00010000UL,  /* This property is an alias name for another property. */
-    kXMP_PropHasAliases       = 0x00020000UL,  /* This property is the base value for a set of aliases. */
-    kXMP_PropIsInternal       = 0x00040000UL,  /* This property is an "internal" property, owned by applications. */
-    kXMP_PropIsStable         = 0x00100000UL,  /* This property is not derived from the document content. */
-    kXMP_PropIsDerived        = 0x00200000UL,  /* This property is derived from the document content. */
-    /* kXMPUtil_AllowCommas   = 0x10000000UL,  ! Used by TXMPUtils::CatenateArrayItems and ::SeparateArrayItems. */
-    /* kXMP_DeleteExisting    = 0x20000000UL,  ! Used by TXMPMeta::SetXyz functions to delete any pre-existing property. */
-    /* kXMP_SchemaNode        = 0x80000000UL,  ! Returned by iterators - #define to avoid warnings */
-
-    /* Masks that are multiple flags. */
+// -------------------------------------------------------------------------------------------------
+
+/// Option bit flags for the \c TXMPMeta property accessor functions.
+enum {
+
+	/// The XML string form of the property value is a URI, use rdf:resource attribute. DISCOURAGED
+    kXMP_PropValueIsURI       = 0x00000002UL,
+
+	// ------------------------------------------------------
+    // Options relating to qualifiers attached to a property.
+
+	/// The property has qualifiers, includes \c rdf:type and \c xml:lang.
+    kXMP_PropHasQualifiers    = 0x00000010UL,
+
+	/// This is a qualifier for some other property, includes \c rdf:type and \c xml:lang.
+	/// Qualifiers can have arbitrary structure, and can themselves have qualifiers. If the
+	/// qualifier itself has a structured value, this flag is only set for the top node of the
+	/// qualifier's subtree.
+    kXMP_PropIsQualifier      = 0x00000020UL,
+
+	/// Implies \c #kXMP_PropHasQualifiers, property has \c xml:lang.
+    kXMP_PropHasLang          = 0x00000040UL,
+
+	/// Implies \c #kXMP_PropHasQualifiers, property has \c rdf:type.
+    kXMP_PropHasType          = 0x00000080UL,
+
+	// --------------------------------------------
+    // Options relating to the data structure form.
+
+	/// The value is a structure with nested fields.
+    kXMP_PropValueIsStruct    = 0x00000100UL,
+
+	/// The value is an array (RDF alt/bag/seq). The "ArrayIs..." flags identify specific types
+	/// of array; default is a general unordered array, serialized using an \c rdf:Bag container.
+    kXMP_PropValueIsArray     = 0x00000200UL,
+
+	/// The item order does not matter.
+    kXMP_PropArrayIsUnordered = kXMP_PropValueIsArray,
+
+	/// Implies \c #kXMP_PropValueIsArray, item order matters. It is serialized using an \c rdf:Seq container.
+    kXMP_PropArrayIsOrdered   = 0x00000400UL,
+
+	/// Implies \c #kXMP_PropArrayIsOrdered, items are alternates. It is serialized using an \c rdf:Alt container.
+    kXMP_PropArrayIsAlternate = 0x00000800UL,
+
+	// ------------------------------------
+    // Additional struct and array options.
+
+	/// Implies \c #kXMP_PropArrayIsAlternate, items are localized text.  Each array element is a
+	/// simple property with an \c xml:lang attribute.
+    kXMP_PropArrayIsAltText   = 0x00001000UL,
+
+    // kXMP_InsertBeforeItem  = 0x00004000UL,  ! Used by SetXyz functions.
+    // kXMP_InsertAfterItem   = 0x00008000UL,  ! Used by SetXyz functions.
+
+	// ----------------------------
+    // Other miscellaneous options.
+
+	/// This property is an alias name for another property.  This is only returned by
+	/// \c TXMPMeta::GetProperty() and then only if the property name is simple, not an path expression.
+    kXMP_PropIsAlias          = 0x00010000UL,
+
+	/// This property is the base value (actual) for a set of aliases.This is only returned by
+	/// \c TXMPMeta::GetProperty() and then only if the property name is simple, not an path expression.
+    kXMP_PropHasAliases       = 0x00020000UL,
+
+	/// The value of this property is "owned" by the application, and should not generally be editable in a UI.
+    kXMP_PropIsInternal       = 0x00040000UL,
+
+	/// The value of this property is not derived from the document content.
+    kXMP_PropIsStable         = 0x00100000UL,
+
+	/// The value of this property is derived from the document content.
+    kXMP_PropIsDerived        = 0x00200000UL,
+
+    // kXMPUtil_AllowCommas   = 0x10000000UL,  ! Used by TXMPUtils::CatenateArrayItems and ::SeparateArrayItems.
+    // kXMP_DeleteExisting    = 0x20000000UL,  ! Used by TXMPMeta::SetXyz functions to delete any pre-existing property.
+    // kXMP_SchemaNode        = 0x80000000UL,  ! Returned by iterators - #define to avoid warnings
+
+	// ------------------------------
+    // Masks that are multiple flags.
+
+	/// Property type bit-flag mask for all array types
     kXMP_PropArrayFormMask    = kXMP_PropValueIsArray | kXMP_PropArrayIsOrdered | kXMP_PropArrayIsAlternate | kXMP_PropArrayIsAltText,
-    kXMP_PropCompositeMask    = kXMP_PropValueIsStruct | kXMP_PropArrayFormMask,  /* Is it simple or composite (array or struct)? */
-    kXMP_ImplReservedMask     = 0x70000000L   /* Reserved for transient use by the implementation. */
+
+	/// Property type bit-flag mask for composite types (array and struct)
+    kXMP_PropCompositeMask    = kXMP_PropValueIsStruct | kXMP_PropArrayFormMask,
+
+	/// Mask for bits that are reserved for transient use by the implementation.
+    kXMP_ImplReservedMask     = 0x70000000L
+
 };
 
 #define kXMP_SchemaNode ((XMP_OptionBits)0x80000000UL)
 
-enum {  /* Option bits for the TXMPMeta::SetXyz functions. */
+/// Option bit flags for the \c TXMPMeta property setting functions. These option bits are shared
+/// with the accessor functions:
+///   \li \c #kXMP_PropValueIsURI
+///   \li \c #kXMP_PropValueIsStruct
+///   \li \c #kXMP_PropValueIsArray
+///   \li \c #kXMP_PropArrayIsOrdered
+///   \li \c #kXMP_PropArrayIsAlternate
+///   \li \c #kXMP_PropArrayIsAltText
+enum {
 
-    /* Options shared with GetXyz functions. */
-    /*
-    kXMP_PropValueIsURI        = 0x00000002UL, DISCOURAGED
-    kXMP_PropValueIsStruct     = 0x00000100UL,
-    kXMP_PropValueIsArray      = 0x00000200UL,
-    kXMP_PropArrayIsOrdered    = 0x00000400UL,
-    kXMP_PropArrayIsAlternate  = 0x00000800UL,
-    kXMP_PropArrayIsAltText    = 0x00001000UL,
-    kXMP_PropValueIsCompact    = 0x00002000UL, RESERVED
-    */
+    /// Option for array item location: Insert a new item before the given index.
+    kXMP_InsertBeforeItem      = 0x00004000UL,
 
-    /* Options for array item location. */
-    kXMP_InsertBeforeItem      = 0x00004000UL,  /* Insert a new item before the given index. */
-    kXMP_InsertAfterItem       = 0x00008000UL,  /* Insert a new item after the given index. */
+    /// Option for array item location: Insert a new item after the given index.
+    kXMP_InsertAfterItem       = 0x00008000UL,
 
-    /* Miscellaneous options */
-    kXMP_DeleteExisting        = 0x20000000UL,  /* Delete any pre-existing property. */
+    /// Delete any pre-existing property.
+    kXMP_DeleteExisting        = 0x20000000UL,
 
-    /* Masks that are multiple flags. */
+	/// Bit-flag mask for property-value option bits
     kXMP_PropValueOptionsMask  = kXMP_PropValueIsURI,
+
+	/// Bit-flag mask for array-item location bits
     kXMP_PropArrayLocationMask = kXMP_InsertBeforeItem | kXMP_InsertAfterItem
 
 };
 
-/* ---------------------------------------------------------------------------------------------- */
+// -------------------------------------------------------------------------------------------------
+
+/// Option bit flags for \c TXMPMeta::ParseFromBuffer().
+enum {
+
+	/// Require a surrounding \c x:xmpmeta element.
+    kXMP_RequireXMPMeta   = 0x0001UL,
+
+	/// This is the not last input buffer for this parse stream.
+    kXMP_ParseMoreBuffers = 0x0002UL,
+
+	/// Do not reconcile alias differences, throw an exception.
+    kXMP_StrictAliasing   = 0x0004UL
 
-enum {  /* Options for TXMPMeta::ParseFromBuffer. */
-    kXMP_RequireXMPMeta   = 0x0001UL,  /* Require a surrounding x:xmpmeta element. */
-    kXMP_ParseMoreBuffers = 0x0002UL,  /* This is the not last input buffer for this parse stream. */
-    kXMP_StrictAliasing   = 0x0004UL   /* Do not reconcile alias differences, throw an exception. */
 };
 
-enum {  /* Options for TXMPMeta::SerializeToBuffer. */
+/// Option bit flags for \c TXMPMeta::SerializeToBuffer().
+enum {
+
+    // *** Option to remove empty struct/array, or leaf with empty value?
+
+	/// Omit the XML packet wrapper.
+    kXMP_OmitPacketWrapper   = 0x0010UL,
+
+	/// Default is a writeable packet.
+    kXMP_ReadOnlyPacket      = 0x0020UL,
+
+	/// Use a compact form of RDF.
+    kXMP_UseCompactFormat    = 0x0040UL,
+
+	/// Include a padding allowance for a thumbnail image.
+    kXMP_IncludeThumbnailPad = 0x0100UL,
 
-    /* *** Option to remove empty struct/array, or leaf with empty value? */
+	/// The padding parameter is the overall packet length.
+    kXMP_ExactPacketLength   = 0x0200UL,
 
-    kXMP_OmitPacketWrapper   = 0x0010UL,  /* Omit the XML packet wrapper. */
-    kXMP_ReadOnlyPacket      = 0x0020UL,  /* Default is a writeable packet. */
-    kXMP_UseCompactFormat    = 0x0040UL,  /* Use a compact form of RDF. */
+	/// Show aliases as XML comments.
+    kXMP_WriteAliasComments  = 0x0400UL,
 
-    kXMP_IncludeThumbnailPad = 0x0100UL,  /* Include a padding allowance for a thumbnail image. */
-    kXMP_ExactPacketLength   = 0x0200UL,  /* The padding parameter is the overall packet length. */
-    kXMP_WriteAliasComments  = 0x0400UL,  /* Show aliases as XML comments. */
-    kXMP_OmitAllFormatting   = 0x0800UL,  /* Omit all formatting whitespace. */
+	/// Omit all formatting whitespace.
+    kXMP_OmitAllFormatting   = 0x0800UL,
+    
+    /// Omit the x:xmpmeta element surrounding the rdf:RDF element.
+    kXMP_OmitXMPMetaElement  = 0x1000UL,
 
-    _XMP_LittleEndian_Bit    = 0x0001UL,  /* ! Don't use directly, see the combined values below! */
+    _XMP_LittleEndian_Bit    = 0x0001UL,  // ! Don't use directly, see the combined values below!
     _XMP_UTF16_Bit           = 0x0002UL,
     _XMP_UTF32_Bit           = 0x0004UL,
 
+	/// Bit-flag mask for encoding-type bits
     kXMP_EncodingMask        = 0x0007UL,
+
+	/// Use UTF8 encoding
     kXMP_EncodeUTF8          = 0UL,
+
+	/// Use UTF16 big-endian encoding
     kXMP_EncodeUTF16Big      = _XMP_UTF16_Bit,
+
+	/// Use UTF16 little-endian encoding
     kXMP_EncodeUTF16Little   = _XMP_UTF16_Bit | _XMP_LittleEndian_Bit,
+
+	/// Use UTF32 big-endian encoding
     kXMP_EncodeUTF32Big      = _XMP_UTF32_Bit,
+
+	/// Use UTF13 little-endian encoding
     kXMP_EncodeUTF32Little   = _XMP_UTF32_Bit | _XMP_LittleEndian_Bit
 
 };
 
-/* ---------------------------------------------------------------------------------------------- */
+// -------------------------------------------------------------------------------------------------
 
-enum {  /* Options for TXMPIterator construction. */
+/// Option bit flags for \c TXMPIterator construction.
+enum {
 
-    kXMP_IterClassMask      = 0x00FFUL,  /* The low 8 bits are an enum of what data structure to iterate. */
-    kXMP_IterProperties     = 0x0000UL,  /* Iterate the property tree of a TXMPMeta object. */
-    kXMP_IterAliases        = 0x0001UL,  /* Iterate the global alias table. */
-    kXMP_IterNamespaces     = 0x0002UL,  /* Iterate the global namespace table. */
-    kXMP_IterJustChildren   = 0x0100UL,  /* Just do the immediate children of the root, default is subtree. */
-    kXMP_IterJustLeafNodes  = 0x0200UL,  /* Just do the leaf nodes, default is all nodes in the subtree. */
-    kXMP_IterJustLeafName   = 0x0400UL,  /* Return just the leaf part of the path, default is the full path. */
-    kXMP_IterIncludeAliases = 0x0800UL,  /* Include aliases, default is just actual properties. */
+	/// The low 8 bits are an enum of what data structure to iterate.
+    kXMP_IterClassMask      = 0x00FFUL,
 
-    kXMP_IterOmitQualifiers = 0x1000UL   /* Omit all qualifiers. */
+    /// Iterate the property tree of a TXMPMeta object.
+    kXMP_IterProperties     = 0x0000UL,
 
-};
+	/// Iterate the global alias table.
+    kXMP_IterAliases        = 0x0001UL,
 
-enum {  /* Options for TXMPIterator::Skip. */
-    kXMP_IterSkipSubtree    = 0x0001UL,  /* Skip the subtree below the current node. */
-    kXMP_IterSkipSiblings   = 0x0002UL   /* Skip the subtree below and remaining siblings of the current node. */
-};
+	/// Iterate the global namespace table.
+    kXMP_IterNamespaces     = 0x0002UL,
 
-/* ---------------------------------------------------------------------------------------------- */
+	/// Just do the immediate children of the root, default is subtree.
+    kXMP_IterJustChildren   = 0x0100UL,
 
-enum {  /* Options for TXMPUtils::CatenateArrayItems and TXMPUtils::SeparateArrayItems. */
+	/// Just do the leaf nodes, default is all nodes in the subtree.
+    kXMP_IterJustLeafNodes  = 0x0200UL,
 
-    /* Options shared with GetXyz functions. */
-    /*
-    kXMP_PropValueIsArray     = 0x00000200UL,
-    kXMP_PropArrayIsOrdered   = 0x00000400UL,
-    kXMP_PropArrayIsAlternate = 0x00000800UL,
-    kXMP_PropArrayIsAltText   = 0x00001000UL,
-    */
+	/// Return just the leaf part of the path, default is the full path.
+    kXMP_IterJustLeafName   = 0x0400UL,
 
-    kXMPUtil_AllowCommas      = 0x10000000UL   /* Allow commas in item values, default is separator. */
+	 /// Include aliases, default is just actual properties.
+    kXMP_IterIncludeAliases = 0x0800UL,
+
+	 /// Omit all qualifiers.
+    kXMP_IterOmitQualifiers = 0x1000UL
 
 };
 
-enum {  /* Options for TXMPUtils::RemoveProperties and TXMPUtils::AppendProperties. */
-    kXMPUtil_DoAllProperties   = 0x0001UL,  /* Do all properties, default is just external properties. */
-    kXMPUtil_ReplaceOldValues  = 0x0002UL,  /* Replace existing values, default is to leave them. */
-    kXMPUtil_DeleteEmptyValues = 0x0004UL,  /* Delete properties if the new value is empty. */
-    kXMPUtil_IncludeAliases    = 0x0800UL   /* == kXMP_IterIncludeAliases */
+/// Option bit flags for \c TXMPIterator::Skip().
+enum {
+
+	/// Skip the subtree below the current node.
+    kXMP_IterSkipSubtree    = 0x0001UL,
+
+	/// Skip the subtree below and remaining siblings of the current node.
+    kXMP_IterSkipSiblings   = 0x0002UL
+
 };
 
-/* ============================================================================================== */
-/* Types and Constants for XMP File Handler */
-/* ======================================== */
+// -------------------------------------------------------------------------------------------------
+/// Option bit flags for \c TXMPUtils::CatenateArrayItems() and \c TXMPUtils::SeparateArrayItems().
+/// These option bits are shared with the accessor functions:
+///   \li \c #kXMP_PropValueIsArray,
+///   \li \c #kXMP_PropArrayIsOrdered, 
+///   \li \c #kXMP_PropArrayIsAlternate,
+///   \li \c #kXMP_PropArrayIsAltText
+enum {
+
+	/// Allow commas in item values, default is separator.
+    kXMPUtil_AllowCommas      = 0x10000000UL
 
+};
+
+/// Option bit flags for \c TXMPUtils::RemoveProperties() and \c TXMPUtils::AppendProperties().
 enum {
 
-    /* Public file formats. Hex used to avoid gcc warnings. */
-    /* ! Leave them as big endian. There seems to be no decent way on UNIX to determine the target */
-    /* ! endianness at compile time. Forcing it on the client isn't acceptable.                    */
+	 /// Do all properties, default is just external properties.
+    kXMPUtil_DoAllProperties   = 0x0001UL,
+
+	/// Replace existing values, default is to leave them.
+    kXMPUtil_ReplaceOldValues  = 0x0002UL,
 
-    kXMP_PDFFile             = 0x50444620UL,  /* 'PDF ' */
-    kXMP_PostScriptFile      = 0x50532020UL,  /* 'PS  ', general PostScript following DSC conventions. */
-    kXMP_EPSFile             = 0x45505320UL,  /* 'EPS ', encapsulated PostScript. */
+	/// Delete properties if the new value is empty.
+    kXMPUtil_DeleteEmptyValues = 0x0004UL,
+
+	/// Include aliases, default is just actual properties.
+    kXMPUtil_IncludeAliases    = 0x0800UL
+
+};
 
-    kXMP_JPEGFile            = 0x4A504547UL,  /* 'JPEG' */
-    kXMP_JPEG2KFile          = 0x4A505820UL,  /* 'JPX ', ISO 15444-1 */
-    kXMP_TIFFFile            = 0x54494646UL,  /* 'TIFF' */
-    kXMP_GIFFile             = 0x47494620UL,  /* 'GIF ' */
-    kXMP_PNGFile             = 0x504E4720UL,  /* 'PNG ' */
+// =================================================================================================
+// Types and Constants for XMPFiles
+// ================================
+
+/// File format constants for use with XMPFiles.
+enum {
     
-    kXMP_SWFFile             = 0x53574620UL,  /* 'SWF ' */
-    kXMP_FLAFile             = 0x464C4120UL,  /* 'FLA ' */
-    kXMP_FLVFile             = 0x464C5620UL,  /* 'FLV ' */
-
-    kXMP_MOVFile             = 0x4D4F5620UL,  /* 'MOV ', Quicktime */
-    kXMP_AVIFile             = 0x41564920UL,  /* 'AVI ' */
-    kXMP_CINFile             = 0x43494E20UL,  /* 'CIN ', Cineon */
-    kXMP_WAVFile             = 0x57415620UL,  /* 'WAV ' */
-    kXMP_MP3File             = 0x4D503320UL,  /* 'MP3 ' */
-    kXMP_SESFile             = 0x53455320UL,  /* 'SES ', Audition session */
-    kXMP_CELFile             = 0x43454C20UL,  /* 'CEL ', Audition loop */
-    kXMP_MPEGFile            = 0x4D504547UL,  /* 'MPEG' */
-    kXMP_MPEG2File           = 0x4D503220UL,  /* 'MP2 ' */
-    kXMP_MPEG4File           = 0x4D503420UL,  /* 'MP4 ', ISO 14494-12 and -14 */
-    kXMP_WMAVFile            = 0x574D4156UL,  /* 'WMAV', Windows Media Audio and Video */
-    kXMP_AIFFFile            = 0x41494646UL,  /* 'AIFF' */
-
-    kXMP_HTMLFile            = 0x48544D4CUL,  /* 'HTML' */
-    kXMP_XMLFile             = 0x584D4C20UL,  /* 'XML ' */
-    kXMP_TextFile            = 0x74657874UL,  /* 'text' */
-
-    /* Adobe application file formats. */
-
-    kXMP_PhotoshopFile       = 0x50534420UL,  /* 'PSD ' */
-    kXMP_IllustratorFile     = 0x41492020UL,  /* 'AI  ' */
-    kXMP_InDesignFile        = 0x494E4444UL,  /* 'INDD' */
-    kXMP_AEProjectFile       = 0x41455020UL,  /* 'AEP ' */
-    kXMP_AEProjTemplateFile  = 0x41455420UL,  /* 'AET ', After Effects Project Template */
-    kXMP_AEFilterPresetFile  = 0x46465820UL,  /* 'FFX ' */
-    kXMP_EncoreProjectFile   = 0x4E434F52UL,  /* 'NCOR' */
-    kXMP_PremiereProjectFile = 0x5052504AUL,  /* 'PRPJ' */
-    kXMP_PremiereTitleFile   = 0x5052544CUL,  /* 'PRTL' */
-
-    /* Catch all. */
-
-    kXMP_UnknownFile         = 0x20202020UL   /* '    ' */
+    // ! Hex used to avoid gcc warnings. Leave the constants so the text reads big endian. There
+    // ! seems to be no decent way on UNIX to determine the target endianness at compile time.
+    // ! Forcing it on the client isn't acceptable.
+
+	// --------------------
+    // Public file formats.
+
+	/// Public file format constant: 'PDF '
+    kXMP_PDFFile             = 0x50444620UL,
+	/// Public file format constant: 'PS  ', general PostScript following DSC conventions
+    kXMP_PostScriptFile      = 0x50532020UL,
+	/// Public file format constant: 'EPS ', encapsulated PostScript
+    kXMP_EPSFile             = 0x45505320UL,
+
+	/// Public file format constant: 'JPEG'
+    kXMP_JPEGFile            = 0x4A504547UL,
+	/// Public file format constant: 'JPX ', JPEG 2000, ISO 15444-1
+    kXMP_JPEG2KFile          = 0x4A505820UL,
+	/// Public file format constant: 'TIFF'
+    kXMP_TIFFFile            = 0x54494646UL,
+	/// Public file format constant: 'GIF '
+    kXMP_GIFFile             = 0x47494620UL,
+	/// Public file format constant: 'PNG '
+    kXMP_PNGFile             = 0x504E4720UL,
+
+	/// Public file format constant: 'SWF '
+    kXMP_SWFFile             = 0x53574620UL,
+	/// Public file format constant: 'FLA '
+    kXMP_FLAFile             = 0x464C4120UL,
+	/// Public file format constant: 'FLV '
+    kXMP_FLVFile             = 0x464C5620UL,
+
+	/// Public file format constant: 'MOV ', Quicktime
+    kXMP_MOVFile             = 0x4D4F5620UL,
+	/// Public file format constant: 'AVI '
+    kXMP_AVIFile             = 0x41564920UL,
+	/// Public file format constant: 'CIN ', Cineon
+    kXMP_CINFile             = 0x43494E20UL,
+ 	/// Public file format constant: 'WAV '
+    kXMP_WAVFile             = 0x57415620UL,
+	/// Public file format constant: 'MP3 '
+    kXMP_MP3File             = 0x4D503320UL,
+	/// Public file format constant: 'SES ', Audition session
+    kXMP_SESFile             = 0x53455320UL,
+	/// Public file format constant: 'CEL ', Audition loop
+    kXMP_CELFile             = 0x43454C20UL,
+	/// Public file format constant: 'MPEG'
+    kXMP_MPEGFile            = 0x4D504547UL,
+	/// Public file format constant: 'MP2 '
+    kXMP_MPEG2File           = 0x4D503220UL,
+	/// Public file format constant: 'MP4 ', ISO 14494-12 and -14
+    kXMP_MPEG4File           = 0x4D503420UL,
+	/// Public file format constant: 'WMAV', Windows Media Audio and Video
+    kXMP_WMAVFile            = 0x574D4156UL,
+	/// Public file format constant:  'AIFF'
+    kXMP_AIFFFile            = 0x41494646UL,
+	/// Public file format constant:  'P2  ', a collection not really a single file
+    kXMP_P2File              = 0x50322020UL,
+	/// Public file format constant:  'XDCF', a collection not really a single file
+    kXMP_XDCAM_FAMFile       = 0x58444346UL,
+	/// Public file format constant:  'XDCS', a collection not really a single file
+    kXMP_XDCAM_SAMFile       = 0x58444353UL,
+	/// Public file format constant:  'XDCX', a collection not really a single file
+    kXMP_XDCAM_EXFile        = 0x58444358UL,
+	/// Public file format constant:  'AVHD', a collection not really a single file
+    kXMP_AVCHDFile           = 0x41564844UL,
+	/// Public file format constant:  'SHDV', a collection not really a single file
+    kXMP_SonyHDVFile         = 0x53484456UL,
+
+	/// Public file format constant: 'HTML'
+    kXMP_HTMLFile            = 0x48544D4CUL,
+	/// Public file format constant: 'XML '
+    kXMP_XMLFile             = 0x584D4C20UL,
+	/// Public file format constant:  'text'
+    kXMP_TextFile            = 0x74657874UL,
+
+	// -------------------------------
+    // Adobe application file formats.
+
+	/// Adobe application file format constant: 'PSD '
+    kXMP_PhotoshopFile       = 0x50534420UL,
+	/// Adobe application file format constant: 'AI  '
+    kXMP_IllustratorFile     = 0x41492020UL,
+	/// Adobe application file format constant: 'INDD'
+    kXMP_InDesignFile        = 0x494E4444UL,
+	/// Adobe application file format constant: 'AEP '
+    kXMP_AEProjectFile       = 0x41455020UL,
+	/// Adobe application file format constant: 'AET ', After Effects Project Template
+    kXMP_AEProjTemplateFile  = 0x41455420UL,
+	/// Adobe application file format constant: 'FFX '
+    kXMP_AEFilterPresetFile  = 0x46465820UL,
+	/// Adobe application file format constant: 'NCOR'
+    kXMP_EncoreProjectFile   = 0x4E434F52UL,
+	/// Adobe application file format constant: 'PRPJ'
+    kXMP_PremiereProjectFile = 0x5052504AUL,
+	/// Adobe application file format constant: 'PRTL'
+    kXMP_PremiereTitleFile   = 0x5052544CUL,
+	/// Adobe application file format constant: 'UCF ', Universal Container Format
+	kXMP_UCFFile             = 0x55434620UL,
+
+	// -------
+    // Others.
+
+	/// Unknown file format constant: '    '
+    kXMP_UnknownFile         = 0x20202020UL
 
 };
+
+/// Type for file format identification constants. See \c #kXMP_PDFFile and following.
 typedef XMP_Uns32 XMP_FileFormat;
 
-/* ---------------------------------------------------------------------------------------------- */
+// -------------------------------------------------------------------------------------------------
 
+/// Byte-order masks, do not use directly
 enum {
     kXMP_CharLittleEndianMask = 1,
-    kXMP_Char16BitMask        = 2,  /* Don't use these directly. */
+    kXMP_Char16BitMask        = 2,
     kXMP_Char32BitMask        = 4
 };
 
-enum {  /* The values allow easy testing for 16/32 bit and big/little endian. */
+/// Constants to allow easy testing for 16/32 bit and big/little endian.
+enum {
+	/// 8-bit
     kXMP_Char8Bit        = 0,
+	/// 16-bit big-endian
     kXMP_Char16BitBig    = kXMP_Char16BitMask,
+	/// 16-bit little-endian
     kXMP_Char16BitLittle = kXMP_Char16BitMask | kXMP_CharLittleEndianMask,
+	/// 32-bit big-endian
     kXMP_Char32BitBig    = kXMP_Char32BitMask,
+	/// 32-bit little-endian
     kXMP_Char32BitLittle = kXMP_Char32BitMask | kXMP_CharLittleEndianMask,
-    kXMP_CharUnknown     = 1 /* ! A bit of a hack, for variable or not-yet-known cases. */
+	/// Variable or not-yet-known cases
+    kXMP_CharUnknown     = 1
 };
 
+/// \name Macros to test components of the character form mask
+/// @{
+///
+/// \def XMP_CharFormIs16Bit
+/// \brief Macro reports the encoding of a character.
+/// \param f The character to check.
+///
+/// \def XMP_CharFormIs32Bit
+/// \brief Macro reports the encoding of a character.
+/// \param f The character to check.
+///
+/// \def XMP_CharFormIsBigEndian
+/// \brief Macro reports the byte-order of a character.
+/// \param f The character to check.
+///
+/// \def XMP_CharFormIsLittleEndian
+/// \brief Macro reports the byte-order of a character.
+/// \param f The character to check.
+///
+/// \def XMP_GetCharSize
+/// \brief Macro reports the byte-size of a character.
+/// \param f The character to check.
+///
+/// \def XMP_CharToSerializeForm
+/// \brief Macro converts \c XMP_Uns8 to \c XMP_OptionBits.
+/// \param cf The character to convert.
+///
+/// \def XMP_CharFromSerializeForm
+/// \brief Macro converts \c XMP_OptionBits to \c XMP_Uns8.
+/// \param sf The character to convert.
+///
+/// @}
+
 #define XMP_CharFormIs16Bit(f)         ( ((int)(f) & kXMP_Char16BitMask) != 0 )
 #define XMP_CharFormIs32Bit(f)         ( ((int)(f) & kXMP_Char32BitMask) != 0 )
-
 #define XMP_CharFormIsBigEndian(f)     ( ((int)(f) & kXMP_CharLittleEndianMask) == 0 )
 #define XMP_CharFormIsLittleEndian(f)  ( ((int)(f) & kXMP_CharLittleEndianMask) != 0 )
-
 #define XMP_GetCharSize(f)             ( ((int)(f)&6) == 0 ? 1 : (int)(f)&6 )
-
 #define XMP_CharToSerializeForm(cf)    ( (XMP_OptionBits)(cf) )
 #define XMP_CharFromSerializeForm(sf)  ( (XMP_Uns8)(sf) )
 
+/// \def kXMPFiles_UnknownOffset
+/// \brief Constant for an unknown packet offset within a file.
+#define kXMPFiles_UnknownOffset	((XMP_Int64)-1)
+
+/// \def kXMPFiles_UnknownLength
+/// \brief Constant for an unknown packet length within a file.
+#define kXMPFiles_UnknownLength	((XMP_Int32)-1)
+
+/// XMP packet description
 struct XMP_PacketInfo {
+
+	/// Packet offset in the file in bytes, -1 if unknown.
     XMP_Int64 offset;
+	/// Packet length in the file in bytes, -1 if unknown.
     XMP_Int32 length;
-    XMP_Int32 padSize;   /* Zero if unknown. */
+	/// Packet padding size in bytes, zero if unknown.
+    XMP_Int32 padSize;   // Zero if unknown.
+
+	/// Character format using the values \c kXMP_Char8Bit, \c kXMP_Char16BitBig, etc.
     XMP_Uns8  charForm;
+	/// True if there is a packet wrapper and the trailer says writeable by dumb packet scanners.
     XMP_Bool  writeable;
-    XMP_Uns8  pad1, pad2;
-    #if __cplusplus
-        XMP_PacketInfo() : offset(0), length(0), padSize(0), charForm(0), writeable(0), pad1(0), pad2(0) {};
-    #endif
+    /// True if there is a packet wrapper, the "<?xpacket...>" XML processing instructions.
+    XMP_Bool  hasWrapper;
+
+	/// Padding to make the struct's size be a multiple 4.
+    XMP_Uns8  pad;
+
+	/// Default constructor.
+	XMP_PacketInfo() : offset(kXMPFiles_UnknownOffset), length(kXMPFiles_UnknownLength),
+					   padSize(0), charForm(0), writeable(0), hasWrapper(0), pad(0) {};
+
 };
-#if ! __cplusplus
-    typedef struct XMP_PacketInfo XMP_PacketInfo;
-#endif
-enum { kXMP_PacketInfoVersion = 3 };
 
-/* ---------------------------------------------------------------------------------------------- */
+/// Version of the XMP_PacketInfo type
+enum {
+	/// Version of the XMP_PacketInfo type
+	kXMP_PacketInfoVersion = 3
+};
+
+// -------------------------------------------------------------------------------------------------
 
-enum {  /* Values for XMP_ThumbnailInfo.tnailFormat. */
-    kXMP_UnknownTNail = 0, /* The thumbnail data has an unknown format. */
-    kXMP_JPEGTNail    = 1, /* The thumbnail data is a JPEG stream, presumably compressed. */
-    kXMP_TIFFTNail    = 2, /* The thumbnail data is a TIFF stream, presumably uncompressed. */
-    kXMP_PShopTNail   = 3  /* The thumbnail data is in the format of Photoshop Image Resource 1036. */
+/// Values for \c XMP_ThumbnailInfo::tnailFormat.
+enum {
+	/// The thumbnail data has an unknown format.
+    kXMP_UnknownTNail = 0,
+	/// The thumbnail data is a JPEG stream, presumably compressed.
+    kXMP_JPEGTNail    = 1,
+	/// The thumbnail data is a TIFF stream, presumably uncompressed.
+    kXMP_TIFFTNail    = 2,
+	/// The thumbnail data is in the format of Photoshop Image Resource 1036.
+    kXMP_PShopTNail   = 3
 };
 
+/// Thumbnail descriptor
 struct XMP_ThumbnailInfo {
-    XMP_FileFormat   fileFormat;  /* The format of the containing file. */
-    XMP_Uns32        fullWidth, fullHeight;    /* Full image size in pixels. */
-    XMP_Uns32        tnailWidth, tnailHeight;  /* Thumbnail image size in pixels. */
-    XMP_Uns16        fullOrientation, tnailOrientation;  /* Orientation of full image and thumbnail, as defined by Exif for tag 274. */
-    const XMP_Uns8 * tnailImage;   /* Raw data from the host file, valid for life of the owning XMPFiles object. Do not modify! */
-    XMP_Uns32        tnailSize;    /* The size in bytes of the tnailImage data. */
-    XMP_Uns8         tnailFormat;  /* The format of the tnailImage data. */
-    XMP_Uns8         pad1, pad2, pad3;
-    #if __cplusplus
-        XMP_ThumbnailInfo() : fileFormat(kXMP_UnknownFile), fullWidth(0), fullHeight(0),
-                              tnailWidth(0), tnailHeight(0), fullOrientation(0), tnailOrientation(0),
-                              tnailImage(0), tnailSize(0), tnailFormat(kXMP_UnknownTNail) {};
-    #endif
-};
-#if ! __cplusplus
-    typedef struct XMP_ThumbnailInfo XMP_ThumbnailInfo;
-#endif
-enum { kXMP_ThumbnailInfoVersion = 1 };
 
-/* ---------------------------------------------------------------------------------------------- */
+	/// The format of the containing file.
+    XMP_FileFormat   fileFormat;
+	/// Full image size in pixels.
+    XMP_Uns32        fullWidth, fullHeight;
+	/// Thumbnail image size in pixels.
+    XMP_Uns32        tnailWidth, tnailHeight;
+	/// Orientation of full image and thumbnail, as defined by Exif for tag 274.
+
+    XMP_Uns16        fullOrientation, tnailOrientation;
+	/// Raw image data from the host file, valid for life of the owning \c XMPFiles object. Do not modify!
+    const XMP_Uns8 * tnailImage;
+	/// The size in bytes of the thumbnail image data.
+    XMP_Uns32        tnailSize;
+	/// The format of the thumbnail image data.
+    XMP_Uns8         tnailFormat;
+
+	/// Padding to make the struct's size be a multiple 4.
+    XMP_Uns8         pad1, pad2, pad3;
 
-#define kXMPFiles_UnknownOffset	((XMP_Int64)-1)
-#define kXMPFiles_UnknownLength	((XMP_Int32)-1)
+	/// Default constructor.
+	XMP_ThumbnailInfo() : fileFormat(kXMP_UnknownFile), fullWidth(0), fullHeight(0),
+						  tnailWidth(0), tnailHeight(0), fullOrientation(0), tnailOrientation(0),
+						  tnailImage(0), tnailSize(0), tnailFormat(kXMP_UnknownTNail) {};
 
-enum {  /* Options for Initialize. */
-    kXMPFiles_NoQuickTimeInit = 0x0001 /* Don't initialize QuickTime, the client will. */
 };
 
-enum {	/* Options for GetFormatInfo. */ 
-    kXMPFiles_CanInjectXMP        = 0x00000001, /* Can inject first-time XMP into an existing file. */
-    kXMPFiles_CanExpand           = 0x00000002, /* Can expand XMP or other metadata in an existing file. */
-    kXMPFiles_CanRewrite          = 0x00000004, /* Can copy one file to another, writing new metadata. */
-    kXMPFiles_PrefersInPlace      = 0x00000008, /* Can expand, but prefers in-place update. */
-    kXMPFiles_CanReconcile        = 0x00000010, /* Supports reconciliation between XMP and other forms. */
-    kXMPFiles_AllowsOnlyXMP       = 0x00000020, /* Allows access to just the XMP, ignoring other forms. */
-    kXMPFiles_ReturnsRawPacket    = 0x00000040, /* File handler returns raw XMP packet information. */
-    kXMPFiles_ReturnsTNail        = 0x00000080, /* File handler returns native thumbnail. */
-    kXMPFiles_HandlerOwnsFile     = 0x00000100, /* The file handler does the file open and close. */
-    kXMPFiles_AllowsSafeUpdate    = 0x00000200,	/* The file handler allows crash-safe file updates. */
-    kXMPFiles_NeedsReadOnlyPacket = 0x00000400,	/* The file format needs the XMP packet to be read-only. */
-    kXMPFiles_UsesSidecarXMP      = 0x00000800	/* The file handler uses a "sidecar" file for the XMP. */
+/// Version of the XMP_ThumbnailInfo type
+enum {
+	/// Version of the XMP_ThumbnailInfo type
+	kXMP_ThumbnailInfoVersion = 1
 };
 
-enum {	/* Options for OpenFile. */
-    kXMPFiles_OpenForRead           = 0x00000001, /* Open for read-only access. */
-    kXMPFiles_OpenForUpdate         = 0x00000002, /* Open for reading and writing. */
-    kXMPFiles_OpenOnlyXMP           = 0x00000004, /* Only the XMP is wanted, allows space/time optimizations. */
-    kXMPFiles_OpenCacheTNail        = 0x00000008, /* Cache thumbnail if possible, GetThumbnail will be called. */
-    kXMPFiles_OpenStrictly          = 0x00000010, /* Be strict about locating XMP and reconciling with other forms. */
-    kXMPFiles_OpenUseSmartHandler   = 0x00000020, /* Require the use of a smart handler. */
-    kXMPFiles_OpenUsePacketScanning = 0x00000040, /* Force packet scanning, don't use a smart handler. */
-    kXMPFiles_OpenLimitedScanning   = 0x00000080, /* Only packet scan files "known" to need scanning. */
-    kXMPFiles_OpenInBackground      = 0x10000000  /* Set if calling from background thread. */
+// -------------------------------------------------------------------------------------------------
+
+/// Option bit flags for \c TXMPFiles::Initialize().
+enum {
+	/// Do not initialize QuickTime, the client will.
+    kXMPFiles_NoQuickTimeInit = 0x0001
 };
 
-/* A note about kXMPFiles_OpenInBackground. The XMPFiles handler for .mov files currently uses      */
-/* QuickTime. On Macintosh, calls to Enter/ExitMovies versus Enter/ExitMoviesOnThread must be made. */
-/* This option is used to signal background use so that the .mov handler can behave appropriately.  */
+/// Option bit flags for \c TXMPFiles::GetFormatInfo().
+enum {
+
+	/// Can inject first-time XMP into an existing file.
+    kXMPFiles_CanInjectXMP        = 0x00000001,
+
+	/// Can expand XMP or other metadata in an existing file.
+    kXMPFiles_CanExpand           = 0x00000002,
+
+	/// Can copy one file to another, writing new metadata.
+    kXMPFiles_CanRewrite          = 0x00000004,
+
+	 /// Can expand, but prefers in-place update.
+    kXMPFiles_PrefersInPlace      = 0x00000008,
+
+	/// Supports reconciliation between XMP and other forms.
+    kXMPFiles_CanReconcile        = 0x00000010,
+
+	 /// Allows access to just the XMP, ignoring other forms.
+    kXMPFiles_AllowsOnlyXMP       = 0x00000020,
+
+	/// File handler returns raw XMP packet information.
+    kXMPFiles_ReturnsRawPacket    = 0x00000040,
+
+	 /// File handler returns native thumbnail.
+    kXMPFiles_ReturnsTNail        = 0x00000080,
+
+	/// The file handler does the file open and close.
+    kXMPFiles_HandlerOwnsFile     = 0x00000100,
+
+	/// The file handler allows crash-safe file updates.
+    kXMPFiles_AllowsSafeUpdate    = 0x00000200,
+
+	/// The file format needs the XMP packet to be read-only.
+    kXMPFiles_NeedsReadOnlyPacket = 0x00000400,
+
+	/// The file handler uses a "sidecar" file for the XMP.
+    kXMPFiles_UsesSidecarXMP      = 0x00000800,
+
+	/// The format is folder oriented, for example the P2 video format.
+    kXMPFiles_FolderBasedFormat   = 0x00001000
 
-enum {	/* Options for CloseFile. */
-    kXMPFiles_UpdateSafely = 0x0001	/* Write into a temporary file and swap for crash safety. */
 };
 
-/* ============================================================================================== */
-/* Exception codes */
-/* =============== */
-
-/**
- *  \name Exception codes.
- *  @{
- *  XMP tookit errors result in throwing an \c XMP_Error exception. Any exception thrown within the
- *  XMP toolkit is caught in the toolkit and rethrown as an \c XMP_Error. The \c XMP_Error struct
- *  contains a numeric code and an English explanation. New numeric codes may be added at any time.
- *  There are typically many possible explanations for each numeric code. The explanations try to
- *  be precise about the specific circumstances causing the error.
- *
- *  \note The explanation string is for debugging use only. It must not be shown to users in a
- *  final product. It is written for developers not users, and never localized.
- */
-
-#if ! __cplusplus
-
-    typedef struct XMP_Error {
-        XMP_Int32     id;
-        XMP_StringPtr errMsg;
-    } XMP_Error;
+/// Option bit flags for \c TXMPFiles::OpenFile().
+enum {
 
-#else
+	/// Open for read-only access.
+    kXMPFiles_OpenForRead           = 0x00000001,
 
-    class XMP_Error {
-    public:
-        XMP_Error ( XMP_Int32 _id, XMP_StringPtr _errMsg ) : id(_id), errMsg(_errMsg) {};
-        inline XMP_Int32     GetID() const     { return id; };
-        inline XMP_StringPtr GetErrMsg() const { return errMsg; };
-    private:
-        XMP_Int32     id;
-        XMP_StringPtr errMsg;
-    };
+	/// Open for reading and writing.
+    kXMPFiles_OpenForUpdate         = 0x00000002,
 
-#endif
+	/// Only the XMP is wanted, allows space/time optimizations.
+    kXMPFiles_OpenOnlyXMP           = 0x00000004,
+
+	/// Cache thumbnail if possible, \c TXMPFiles::GetThumbnail() will be called.
+    kXMPFiles_OpenCacheTNail        = 0x00000008,
+
+	/// Be strict about locating XMP and reconciling with other forms.
+    kXMPFiles_OpenStrictly          = 0x00000010,
 
+	/// Require the use of a smart handler.
+    kXMPFiles_OpenUseSmartHandler   = 0x00000020,
+
+	/// Force packet scanning, do not use a smart handler.
+    kXMPFiles_OpenUsePacketScanning = 0x00000040,
+
+	/// Only packet scan files "known" to need scanning.
+    kXMPFiles_OpenLimitedScanning   = 0x00000080,
+    
+    /// Attempt to repair a file opened for update, default is to not open (throw an exception).
+    kXMPFiles_OpenRepairFile        = 0x00000100,
+
+	 /// Set if calling from background thread.
+    kXMPFiles_OpenInBackground      = 0x10000000
+
+};
+
+// A note about kXMPFiles_OpenInBackground. The XMPFiles handler for .mov files currently uses
+// QuickTime. On Macintosh, calls to Enter/ExitMovies versus Enter/ExitMoviesOnThread must be made.
+// This option is used to signal background use so that the .mov handler can behave appropriately.
+
+/// Option bit flags for \c TXMPFiles::CloseFile().
 enum {
+	/// Write into a temporary file and swap for crash safety.
+    kXMPFiles_UpdateSafely = 0x0001
+};
+
+// =================================================================================================
+// Exception codes
+// ===============
+
+/// \name Errors Exception handling
+/// @{
+///
+/// XMP Tookit errors result in throwing an \c XMP_Error exception. Any exception thrown within the
+/// XMP Toolkit is caught in the toolkit and rethrown as an \c XMP_Error.
+///
+/// The \c XMP_Error class contains a numeric code and an English explanation. New numeric codes may
+/// be added at any time. There are typically many possible explanations for each numeric code. The
+/// explanations try to be precise about the specific circumstances causing the error.
+///
+/// \note The explanation string is for debugging use only. It must not be shown to users in a
+/// final product. It is written for developers not users, and never localized.
+///
+
+/// XMP Toolkit error, associates an error code with a descriptive error string.
+class XMP_Error {
+public:
+
+	/// @brief Constructor for an XMP_Error.
+	///
+	/// @param _id The numeric code.
+	///
+	/// @param _errMsg The descriptive string, for debugging use only. It must not be shown to users
+	/// in a final product. It is written for developers, not users, and never localized.
+	XMP_Error ( XMP_Int32 _id, XMP_StringPtr _errMsg ) : id(_id), errMsg(_errMsg) {};
+
+	/// Retrieves the numeric code from an XMP_Error.
+	inline XMP_Int32     GetID() const     { return id; };
+
+	/// Retrieves the descriptive string from an XMP_Error.
+	inline XMP_StringPtr GetErrMsg() const { return errMsg; };
+
+private:
+	/// Exception code. See constants \c #kXMPErr_Unknown and following.
+	XMP_Int32     id;
+	/// Descriptive string, for debugging use only. It must not be shown to users in a final
+	/// product. It is written for developers, not users, and never localized.
+	XMP_StringPtr errMsg;
+};
 
-    /* More or less generic error codes. */
+/// Exception code constants
+enum {
+
+	// --------------------
+    // Generic error codes.
+   
+	/// Generic unknown error
     kXMPErr_Unknown          =   0,
+	/// Generic undefined error
     kXMPErr_TBD              =   1,
+	/// Generic unavailable error
     kXMPErr_Unavailable      =   2,
+	/// Generic bad object error
     kXMPErr_BadObject        =   3,
+	/// Generic bad parameter error
     kXMPErr_BadParam         =   4,
+	/// Generic bad value error
     kXMPErr_BadValue         =   5,
+	/// Generic assertion failure
     kXMPErr_AssertFailure    =   6,
+	/// Generic enforcement failure
     kXMPErr_EnforceFailure   =   7,
+	/// Generic unimplemented error
     kXMPErr_Unimplemented    =   8,
+	/// Generic internal failure
     kXMPErr_InternalFailure  =   9,
+	/// Generic deprecated error
     kXMPErr_Deprecated       =  10,
+	/// Generic external failure
     kXMPErr_ExternalFailure  =  11,
+	/// Generic user abort error
     kXMPErr_UserAbort        =  12,
+	/// Generic standard exception
     kXMPErr_StdException     =  13,
+	/// Generic unknown exception
     kXMPErr_UnknownException =  14,
+	/// Generic out-of-memory error
     kXMPErr_NoMemory         =  15,
 
-    /* More specific parameter error codes.  */
+	// ------------------------------------
+    // More specific parameter error codes.
+
+	/// Bad schema parameter
     kXMPErr_BadSchema        = 101,
+	/// Bad XPath parameter
     kXMPErr_BadXPath         = 102,
+	/// Bad options parameter
     kXMPErr_BadOptions       = 103,
+	/// Bad index parameter
     kXMPErr_BadIndex         = 104,
+	/// Bad iteration position
     kXMPErr_BadIterPosition  = 105,
+	/// XML parsing error
     kXMPErr_BadParse         = 106,
+	/// Serialization error
     kXMPErr_BadSerialize     = 107,
+	/// File format error
     kXMPErr_BadFileFormat    = 108,
+	/// No file handler found for format
     kXMPErr_NoFileHandler    = 109,
+	/// Data too large for JPEG file format
     kXMPErr_TooLargeForJPEG  = 110,
 
-    /* File format and internal structure error codes. */
+	// -----------------------------------------------
+    // File format and internal structure error codes.
+
+	/// XML format error
     kXMPErr_BadXML           = 201,
+	/// RDF format error
     kXMPErr_BadRDF           = 202,
+	/// XMP format error
     kXMPErr_BadXMP           = 203,
+	/// Empty iterator
     kXMPErr_EmptyIterator    = 204,
+	/// Unicode error
     kXMPErr_BadUnicode       = 205,
+	/// TIFF format error
     kXMPErr_BadTIFF          = 206,
+	/// JPEG format error
     kXMPErr_BadJPEG          = 207,
+	/// PSD format error
     kXMPErr_BadPSD           = 208,
+	/// PSIR format error
     kXMPErr_BadPSIR          = 209,
+	/// IPTC format error
     kXMPErr_BadIPTC          = 210,
+	/// MPEG format error
     kXMPErr_BadMPEG          = 211
 
 };
 
-/**
- *  @}
- */
-
-
-/* ============================================================================================== */
-/* Client callbacks */
-/* ================ */
-
+/// @}
 
-/**
- *  \name Special purpose callback functions
- *  @{
- */
+// =================================================================================================
+// Client callbacks
+// ================
 
-/**
- *  \typedef XMP_Status
- *  \brief A signed 32 bit integer used as a status result for the output callback routine.
- *  Zero means no error, all other values except -1 are private to the callback. The callback is
- *  wrapped to prevent exceptions being thrown across DLL boundaries. Any exceptions thrown out
- *  of the callback cause a return status of -1.
- */
+// -------------------------------------------------------------------------------------------------
+/// \name Special purpose callback functions
+/// @{
 
-/**
- *  \typedef XMP_TextOutputProc
- *  \brief Direct text output from the XMP toolkit, such as debugging dumps, is done using client
- *  supplied callbacks. The callback is invoked one or more times for each line of output. The
- *  end of a line is signaled by a '\n' character at the end of the buffer. Formatting newlines
- *  are never present in the middle of a buffer, but values of properties might contain any UTF-8
- *  characters.  A success/fail status is returned by the callback. Any failure result aborts
- *  the output.
- */
+/// A signed 32-bit integer used as a status result for the output callback routine,
+/// \c XMP_TextOutputProc. Zero means no error, all other values except -1 are private to the callback.
+/// The callback is wrapped to prevent exceptions being thrown across DLL boundaries. Any exceptions
+/// thrown out of the callback cause a return status of -1.
 
 typedef XMP_Int32 XMP_Status;
 
+// -------------------------------------------------------------------------------------------------
+/// The signature of a client-defined callback for text output from XMP Toolkit debugging
+/// operations. The callback is invoked one or more times for each line of output. The end of a line
+/// is signaled by a '\\n' character at the end of the buffer. Formatting newlines are never present
+/// in the middle of a buffer, but values of properties might contain any UTF-8 characters.
+///
+/// @param refCon A pointer to client-defined data passed to the TextOutputProc.
+///
+/// @param buffer  A string containing one line of output.
+///
+/// @param bufferSize The number of characters in the output buffer.
+///
+/// @return A success/fail status value. Any failure result aborts the output.
+///
+/// @see \c TXMPMeta::DumpObject()
+
 typedef XMP_Status (* XMP_TextOutputProc) ( void *        refCon,
                                             XMP_StringPtr buffer,
                                             XMP_StringLen bufferSize );
 
-/**
- *  @}
- */
+// -------------------------------------------------------------------------------------------------
+/// The signature of a client-defined callback to check for a user request to abort a time-consuming
+/// operation within XMPFiles.
+///
+/// @param arg A pointer to caller-defined data passed from the registration call.
+///
+/// @return True to abort the current operation, which results in an exception being thrown.
+///
+/// @see \c TXMPFiles::SetAbortProc()
+
+typedef bool (* XMP_AbortProc) ( void * arg );	// Used by .
 
+/// @}
 
-/* ============================================================================================== */
-/* Stuff with no better place to be */
-/* ================================ */
+// =================================================================================================
+// Stuff with no better place to be
+// ================================
 
+/// XMP Toolkit version information
 typedef struct XMP_VersionInfo {
-    XMP_Uns8      major;    /* The primary release number, the "1" in version "1.2.3". */
-    XMP_Uns8      minor;    /* The secondary release number, the "2" in version "1.2.3". */
-    XMP_Uns8      micro;    /* The tertiary release number, the "3" in version "1.2.3". */
-    XMP_Bool      isDebug;  /* Really a 0/1 bool value. True if this is a debug build. */
-    XMP_Uns32     build;    /* A rolling build number, monotonically increasing in a release. */
-    XMP_Uns32     flags;    /* Individual feature implementation flags. */
-    XMP_StringPtr message;  /* A comprehensive version information string. */
+	/// The primary release number, the "1" in version "1.2.3".
+    XMP_Uns8      major;
+	/// The secondary release number, the "2" in version "1.2.3".
+    XMP_Uns8      minor;
+	/// The tertiary release number, the "3" in version "1.2.3".
+    XMP_Uns8      micro;
+	 /// A 0/1 boolean value, true if this is a debug build.
+    XMP_Bool      isDebug;
+	 /// A rolling build number, monotonically increasing in a release.
+    XMP_Uns32     build;
+	 /// Individual feature implementation flags.
+    XMP_Uns32     flags;
+	 /// A comprehensive version information string.
+    XMP_StringPtr message;
 } XMP_VersionInfo;
 
-typedef bool (* XMP_AbortProc) ( void * arg );	/* Used by SXMPFiles::SetAbortProc. */
-
-/* ============================================================================================== */
+// =================================================================================================
 
 #if __cplusplus
-} /* extern "C" */
+} // extern "C"
 #endif
 
-#endif  /* __XMP_Const_h__ */
+#endif  // __XMP_Const_h__
diff --git a/public/include/XMP_Environment.h b/public/include/XMP_Environment.h
index f25676e..8a77e2c 100644
--- a/public/include/XMP_Environment.h
+++ b/public/include/XMP_Environment.h
@@ -1,11 +1,6 @@
 #ifndef __XMP_Environment_h__
 #define __XMP_Environment_h__ 1
 
-/* --------------------------------------------------------------------------------------------- */
-/* ** IMPORTANT ** This file must be usable by strict ANSI C compilers. No "//" comments, etc.   */
-/* --------------------------------------------------------------------------------------------- */
-
-/*
 // =================================================================================================
 // XMP_Environment.h - Build environment flags for the XMP toolkit.
 // ================================================================
@@ -14,9 +9,7 @@
 // It must be the first #include in any chain since it might affect things in other #includes.
 //
 // =================================================================================================
-*/
 
-/*
 // =================================================================================================
 // Copyright 2002-2007 Adobe Systems Incorporated
 // All Rights Reserved.
@@ -24,22 +17,21 @@
 // NOTICE:  Adobe permits you to use, modify, and distribute this file in accordance with the terms
 // of the Adobe license agreement accompanying it.
 // =================================================================================================
-*/
 
-/* ============================================================================================== */
-/* Determine the Platform */
-/* ====================== */
+// =================================================================================================
+// Determine the Platform
+// ======================
 
-/* One of MAC_ENV, WIN_ENV, or UNIX_ENV must be defined by the client. Since some other code   */
-/* requires these to be defined without values, they are only used here to define XMP-specific */
-/* macros with 0 or 1 values.                                                                  */
+// One of MAC_ENV, WIN_ENV, or UNIX_ENV must be defined by the client. Since some other code
+// requires these to be defined without values, they are only used here to define XMP-specific
+// macros with 0 or 1 values.
 
-/* ! Tempting though it might be to have a standard macro for big or little endian, there seems    */
-/* ! to be no decent way to do that on our own in UNIX. Forcing it on the client isn't acceptable. */
+// ! Tempting though it might be to have a standard macro for big or little endian, there seems to
+// ! be no decent way to do that on our own in UNIX. Forcing it on the client isn't acceptable.
 
 #if defined ( MAC_ENV )
 
-	#if 0	/* ! maybe someday - ! MAC_ENV */
+	#if 0	// ! maybe someday - ! MAC_ENV
 		#error "MAC_ENV must be defined so that \"#if MAC_ENV\" is true"
 	#endif
 	
@@ -53,7 +45,7 @@
 
 #elif defined ( WIN_ENV )
 
-	#if 0	/* ! maybe someday - ! WIN_ENV */
+	#if 0	// ! maybe someday - ! WIN_ENV
 		#error "WIN_ENV must be defined so that \"#if WIN_ENV\" is true"
 	#endif
 	
@@ -67,7 +59,7 @@
 
 #elif defined ( UNIX_ENV )
 
-	#if 0	/* ! maybe someday - ! UNIX_ENV */
+	#if 0	// ! maybe someday - ! UNIX_ENV
 		#error "UNIX_ENV must be defined so that \"#if UNIX_ENV\" is true"
 	#endif
 	
@@ -81,9 +73,9 @@
 
 #endif
 
-/* ============================================================================================== */
-/* Common Macros */
-/* ============= */
+// =================================================================================================
+// Common Macros
+// =============
 
 #if defined ( DEBUG )
     #if defined ( NDEBUG )
@@ -101,21 +93,29 @@
 #endif
 
 #if XMP_DebugBuild
-    #include <stdio.h>  /* The assert macro needs printf. */
+    #include <stdio.h>  // The assert macro needs printf.
+#endif
+
+#ifndef XMP_64
+	#if _WIN64
+		#define XMP_64 1
+	#else
+		#define XMP_64 0
+	#endif
 #endif
 
-/* ============================================================================================== */
-/* Macintosh Specific Settings */
-/* =========================== */
+// =================================================================================================
+// Macintosh Specific Settings
+// ===========================
 
-/* ============================================================================================== */
-/* Windows Specific Settings */
-/* ========================= */
+// =================================================================================================
+// Windows Specific Settings
+// =========================
 
-/* ============================================================================================== */
-/* UNIX Specific Settings */
-/* ====================== */
+// =================================================================================================
+// UNIX Specific Settings
+// ======================
 
-/* ============================================================================================== */
+// =================================================================================================
 
-#endif  /* __XMP_Environment_h__ */
+#endif  // __XMP_Environment_h__
diff --git a/public/include/XMP_Version.h b/public/include/XMP_Version.h
index ed41d14..0c842d0 100644
--- a/public/include/XMP_Version.h
+++ b/public/include/XMP_Version.h
@@ -7,7 +7,7 @@
 
 /*
 // =================================================================================================
-// Copyright 2002-2007 Adobe Systems Incorporated
+// Copyright 2002-2008 Adobe Systems Incorporated
 // All Rights Reserved.
 //
 // NOTICE:  Adobe permits you to use, modify, and distribute this file in accordance with the terms
@@ -34,11 +34,11 @@ versions.
 /* ============================================================================================= */
 
 #define XMP_API_VERSION_MAJOR  4
-#define XMP_API_VERSION_MINOR  1
-#define XMP_API_VERSION_MICRO  1
+#define XMP_API_VERSION_MINOR  4
+#define XMP_API_VERSION_MICRO  0
 
-#define XMP_API_VERSION 4.1
-#define XMP_API_VERSION_STRING "4.1.1"
+#define XMP_API_VERSION 4.4
+#define XMP_API_VERSION_STRING "4.4.0"
 
 /* ============================================================================================= */
 
diff --git a/public/include/client-glue/TXMPFiles.incl_cpp b/public/include/client-glue/TXMPFiles.incl_cpp
index 83867df..ae8a831 100644
--- a/public/include/client-glue/TXMPFiles.incl_cpp
+++ b/public/include/client-glue/TXMPFiles.incl_cpp
@@ -11,7 +11,7 @@
 /// \file TXMPFiles.incl_cpp
 /// \brief The implementation of the TXMPFiles template class.
 
-#if WIN_ENV
+#if XMP_WinBuild
 	#pragma warning ( disable : 4003 )	// not enough actual parameters for macro
 	#pragma warning ( disable : 4800 )	// forcing value to bool 'true' or 'false' (performance warning)
 #endif
@@ -203,6 +203,24 @@ GetInternalRef()
 
 // -------------------------------------------------------------------------------------------------
 
+XMP_MethodIntro(TXMPFiles,XMP_FileFormat)::
+CheckFileFormat ( XMP_StringPtr filePath )
+{
+	WrapCheckFormat ( format, zXMPFiles_CheckFileFormat_1 ( filePath ) );
+	return format;
+}
+
+// -------------------------------------------------------------------------------------------------
+
+XMP_MethodIntro(TXMPFiles,XMP_FileFormat)::
+CheckPackageFormat ( XMP_StringPtr folderPath )
+{
+	WrapCheckFormat ( format, zXMPFiles_CheckPackageFormat_1 ( folderPath ) );
+	return format;
+}
+
+// -------------------------------------------------------------------------------------------------
+
 XMP_MethodIntro(TXMPFiles,bool)::
 OpenFile ( XMP_StringPtr  filePath,
 		   XMP_FileFormat format /* = kXMP_UnknownFile */,
@@ -314,7 +332,7 @@ PutXMP ( XMP_StringPtr xmpPacket,
 XMP_MethodIntro(TXMPFiles,void)::
 PutXMP ( const tStringObj & xmpPacket )
 {
-	this->PutXMP ( xmpPacket.c_str(), xmpPacket.size() );
+	this->PutXMP ( xmpPacket.c_str(), (XMP_StringLen)xmpPacket.size() );
 }
 
 // -------------------------------------------------------------------------------------------------
@@ -341,7 +359,7 @@ CanPutXMP ( XMP_StringPtr xmpPacket,
 XMP_MethodIntro(TXMPFiles,bool)::
 CanPutXMP ( const tStringObj & xmpPacket )
 {
-	return this->CanPutXMP ( xmpPacket.c_str(), xmpPacket.size() );
+	return this->CanPutXMP ( xmpPacket.c_str(), (XMP_StringLen)xmpPacket.size() );
 }
 
 // =================================================================================================
diff --git a/public/include/client-glue/TXMPMeta.incl_cpp b/public/include/client-glue/TXMPMeta.incl_cpp
index 60bd8e7..624198b 100644
--- a/public/include/client-glue/TXMPMeta.incl_cpp
+++ b/public/include/client-glue/TXMPMeta.incl_cpp
@@ -1,6 +1,6 @@
 // =================================================================================================
 // ADOBE SYSTEMS INCORPORATED
-// Copyright 2002-2007 Adobe Systems Incorporated
+// Copyright 2002-2008 Adobe Systems Incorporated
 // All Rights Reserved
 //
 // NOTICE:	Adobe permits you to use, modify, and distribute this file in accordance with the terms
@@ -37,8 +37,6 @@
 #endif
 
 // =================================================================================================
-
-// =================================================================================================
 // Local utilities
 // ===============
 
@@ -857,6 +855,22 @@ SetObjectOptions ( XMP_OptionBits options )
 
 // -------------------------------------------------------------------------------------------------
 
+XMP_MethodIntro(TXMPMeta,void)::
+Sort()
+{
+	WrapCheckVoid ( zXMPMeta_Sort_1() );
+}
+
+// -------------------------------------------------------------------------------------------------
+
+XMP_MethodIntro(TXMPMeta,void)::
+Erase()
+{
+	WrapCheckVoid ( zXMPMeta_Erase_1() );
+}
+
+// -------------------------------------------------------------------------------------------------
+
 XMP_MethodIntro(TXMPMeta,TXMPMeta<tStringObj>)::
 Clone ( XMP_OptionBits options ) const
 {
diff --git a/public/include/client-glue/TXMPUtils.incl_cpp b/public/include/client-glue/TXMPUtils.incl_cpp
index 761ac4e..2ab5745 100644
--- a/public/include/client-glue/TXMPUtils.incl_cpp
+++ b/public/include/client-glue/TXMPUtils.incl_cpp
@@ -1,6 +1,6 @@
 // =================================================================================================
 // ADOBE SYSTEMS INCORPORATED
-// Copyright 2002-2007 Adobe Systems Incorporated
+// Copyright 2002-2008 Adobe Systems Incorporated
 // All Rights Reserved
 //
 // NOTICE:	Adobe permits you to use, modify, and distribute this file in accordance with the terms
@@ -489,3 +489,5 @@ DuplicateSubtree ( const TXMPMeta<tStringObj> & source,
 }
 
 // =================================================================================================
+
+// =================================================================================================
diff --git a/public/include/client-glue/WXMPFiles.hpp b/public/include/client-glue/WXMPFiles.hpp
index 556ad54..cdc510c 100644
--- a/public/include/client-glue/WXMPFiles.hpp
+++ b/public/include/client-glue/WXMPFiles.hpp
@@ -52,6 +52,12 @@ extern "C" {
 #define zXMPFiles_GetFormatInfo_1(format,flags) \
 	WXMPFiles_GetFormatInfo_1 ( format, flags, &wResult )
 
+#define zXMPFiles_CheckFileFormat_1(filePath) \
+	WXMPFiles_CheckFileFormat_1 ( filePath, &wResult )
+
+#define zXMPFiles_CheckPackageFormat_1(folderPath) \
+	WXMPFiles_CheckPackageFormat_1 ( folderPath, &wResult )
+
 #define zXMPFiles_OpenFile_1(filePath,format,openFlags) \
 	WXMPFiles_OpenFile_1 ( this->xmpFilesRef, filePath, format, openFlags, &wResult )
     
@@ -100,6 +106,12 @@ extern void WXMPFiles_GetFormatInfo_1 ( XMP_FileFormat   format,
                                         XMP_OptionBits * flags,	// ! Can be null.
                                         WXMP_Result *    result );
 
+extern void WXMPFiles_CheckFileFormat_1 ( XMP_StringPtr filePath,
+                               			  WXMP_Result * result );
+
+extern void WXMPFiles_CheckPackageFormat_1 ( XMP_StringPtr folderPath,
+                      						 WXMP_Result * result );
+
 extern void WXMPFiles_OpenFile_1 ( XMPFilesRef    xmpFilesRef,
                                    XMP_StringPtr  filePath,
 					               XMP_FileFormat format,
diff --git a/public/include/client-glue/WXMPMeta.hpp b/public/include/client-glue/WXMPMeta.hpp
index 608da15..38eb5db 100644
--- a/public/include/client-glue/WXMPMeta.hpp
+++ b/public/include/client-glue/WXMPMeta.hpp
@@ -2,7 +2,7 @@
 #define __WXMPMeta_hpp__ 1
 
 // =================================================================================================
-// Copyright 2002-2007 Adobe Systems Incorporated
+// Copyright 2002-2008 Adobe Systems Incorporated
 // All Rights Reserved.
 //
 // NOTICE:  Adobe permits you to use, modify, and distribute this file in accordance with the terms
@@ -162,6 +162,12 @@ extern "C" {
 #define zXMPMeta_SetObjectOptions_1(options) \
     WXMPMeta_SetObjectOptions_1 ( this->xmpRef, options, &wResult )
 
+#define zXMPMeta_Sort_1() \
+    WXMPMeta_Sort_1 ( this->xmpRef, &wResult )
+
+#define zXMPMeta_Erase_1() \
+    WXMPMeta_Erase_1 ( this->xmpRef, &wResult )
+
 #define zXMPMeta_Clone_1(options) \
     WXMPMeta_Clone_1 ( this->xmpRef, options, &wResult )
 
@@ -565,6 +571,14 @@ WXMPMeta_SetObjectOptions_1 ( XMPMetaRef     xmpRef,
                               WXMP_Result *  wResult );
 
 extern void
+WXMPMeta_Sort_1 ( XMPMetaRef    xmpRef,
+                  WXMP_Result * wResult );
+
+extern void
+WXMPMeta_Erase_1 ( XMPMetaRef    xmpRef,
+                   WXMP_Result * wResult );
+
+extern void
 WXMPMeta_Clone_1 ( XMPMetaRef     xmpRef,
                    XMP_OptionBits options,
                    WXMP_Result *  wResult ) /* const */ ;
diff --git a/public/include/client-glue/WXMPUtils.hpp b/public/include/client-glue/WXMPUtils.hpp
index fa82f7d..55890fc 100644
--- a/public/include/client-glue/WXMPUtils.hpp
+++ b/public/include/client-glue/WXMPUtils.hpp
@@ -2,7 +2,7 @@
 #define __WXMPUtils_hpp__ 1
 
 // =================================================================================================
-// Copyright 2002-2007 Adobe Systems Incorporated
+// Copyright 2002-2008 Adobe Systems Incorporated
 // All Rights Reserved.
 //
 // NOTICE:  Adobe permits you to use, modify, and distribute this file in accordance with the terms
diff --git a/public/include/client-glue/WXMP_Common.hpp b/public/include/client-glue/WXMP_Common.hpp
index b21e67e..4d6eaab 100644
--- a/public/include/client-glue/WXMP_Common.hpp
+++ b/public/include/client-glue/WXMP_Common.hpp
@@ -33,12 +33,13 @@ struct WXMP_Result {
 extern "C" {
 #endif
 
+#define PropagateException(res)	\
+	if ( res.errMessage != 0 ) throw XMP_Error ( res.int32Result, res.errMessage );
+
 #ifndef TraceXMPCalls
 	#define TraceXMPCalls	0
 #endif
 
-    #define PropagateException(res)	\
-        if ( res.errMessage != 0 ) throw XMP_Error ( res.int32Result, res.errMessage );
 #if ! TraceXMPCalls
 	#define InvokeCheck(WCallProto) \
     	WXMP_Result wResult;        \
@@ -73,10 +74,18 @@ extern "C" {
     InvokeCheck(WCallProto);                \
     XMPIteratorRef result = XMPIteratorRef(wResult.ptrResult)
 
+#define WrapCheckDocOpsRef(result,WCallProto) \
+    InvokeCheck(WCallProto);                  \
+    XMPDocOpsRef result = XMPDocOpsRef(wResult.ptrResult)
+
 #define WrapCheckBool(result,WCallProto) \
     InvokeCheck(WCallProto);             \
     bool result = bool(wResult.int32Result)
 
+#define WrapCheckTriState(result,WCallProto) \
+    InvokeCheck(WCallProto);                 \
+    XMP_TriState result = XMP_TriState(wResult.int32Result)
+
 #define WrapCheckOptions(result,WCallProto) \
     InvokeCheck(WCallProto);                \
     XMP_OptionBits result = XMP_OptionBits(wResult.int32Result)
@@ -101,6 +110,10 @@ extern "C" {
     InvokeCheck(WCallProto);              \
     double result = wResult.floatResult
 
+#define WrapCheckFormat(result,WCallProto) \
+    InvokeCheck(WCallProto);               \
+    XMP_FileFormat result = wResult.int32Result
+
 // =================================================================================================
 
 #if __cplusplus