"doxygenized" comments in tools/inc

This is a follow-up patch to c8b7aa55138848fe07108779099267424bc03e3d.

Change-Id: I124d01ff13d12ea392e6ef283a585d63b1b82e1e

13 files changed, 217 insertions, 254 deletions

diff --git a/tools/inc/bootstrp/prj.hxx b/tools/inc/bootstrp/prj.hxx
index 33116710dd3a..f4525e6bef01 100644
--- a/tools/inc/bootstrp/prj.hxx
+++ b/tools/inc/bootstrp/prj.hxx
@@ -24,12 +24,7 @@
 #include <tools/stream.hxx>
 #include <rtl/string.hxx>
 
-/*********************************************************************
-*
-*   This class can be used for extracting tokens from a file
-*
-*********************************************************************/
-
+/// This class can be used for extracting tokens from a file
 class SimpleConfig
 {
     SvFileStream aFileStream;
diff --git a/tools/inc/impcont.hxx b/tools/inc/impcont.hxx
index 3bc0d90b09fb..87b963880fe5 100644
--- a/tools/inc/impcont.hxx
+++ b/tools/inc/impcont.hxx
@@ -32,22 +32,22 @@ typedef void* PVOID;
 class CBlock
 {
 private:
-    CBlock*         pPrev;              // Previous block
-    CBlock*         pNext;              // Next block
-    sal_uInt16      nSize;              // block size
-    sal_uInt16      nCount;             // number of pointers
-    void**          pNodes;             // stores node pointers
+    CBlock*         pPrev;  ///< Previous block
+    CBlock*         pNext;  ///< Next block
+    sal_uInt16      nSize;  ///< block size
+    sal_uInt16      nCount; ///< number of pointers
+    void**          pNodes; ///< stores node pointers
 
 #if defined DBG_UTIL
     static char const * DbgCheckCBlock(void const *);
 #endif
 
 public:
-                    // used for list container
+                    /// used for list container
                     CBlock( sal_uInt16 nSize, CBlock* pPrev, CBlock* pNext );
-                    // used for array container
+                    /// used for array container
                     CBlock( sal_uInt16 nSize, CBlock* pPrev );
-                    // Copy-Ctor
+                    /// Copy-Ctor
                     CBlock( const CBlock& r, CBlock* pPrev );
                     ~CBlock();
 
@@ -74,28 +74,15 @@ private:
     friend class Container;
 };
 
-/*************************************************************************
-|*
-|*    CBlock::GetObject()
-|*
-|*    Description      Returns a node pointer given a block index
-|*
-*************************************************************************/
-
+/// @return a node pointer given a block index
 inline void* CBlock::GetObject( sal_uInt16 nIndex ) const
 {
     return pNodes[nIndex];
 }
 
-/*************************************************************************
-|*
-|*    Container::ImpGetObject()
-|*
-|*    Description       A pointer is often located in the first block,
-|*                      thus check this position before calling GetObject
-|*
-*************************************************************************/
-
+/** A pointer is often located in the first block, thus check this position
+    before calling GetObject.
+ */
 inline void* Container::ImpGetObject( sal_uIntPtr nIndex ) const
 {
     if ( pFirstBlock && (nIndex < pFirstBlock->Count()) )
@@ -105,19 +92,12 @@ inline void* Container::ImpGetObject( sal_uIntPtr nIndex ) const
         return GetObject( nIndex );
 }
 
-/*************************************************************************
-|*
-|*    Container::ImpGetOnlyNodes()
-|*
-|*    Description       If only one block exists, return its data array
-|*
-*************************************************************************/
-
 // #i70651#: Prevent warnings on Mac OS X
 #ifdef MACOSX
 #pragma GCC system_header
 #endif
 
+/// If only one block exists, return its data array.
 inline void** Container::ImpGetOnlyNodes() const
 {
     if ( (pFirstBlock == pLastBlock) && pFirstBlock )
diff --git a/tools/inc/tools/appendunixshellword.hxx b/tools/inc/tools/appendunixshellword.hxx
index 215a7fed89e7..94b0421efc8a 100644
--- a/tools/inc/tools/appendunixshellword.hxx
+++ b/tools/inc/tools/appendunixshellword.hxx
@@ -33,14 +33,14 @@ namespace rtl {
 
 namespace tools {
 
-// append arbitrary bytes as a properly quoted Unix-style shell word
-//
-// @param accumulator
-// the string buffer to which the word is appended (without any surrounding
-// whitespace); must not be null
-//
-// @param text
-// the text to add
+/** append arbitrary bytes as a properly quoted Unix-style shell word
+
+    @param accumulator
+        the string buffer to which the word is appended (without any surrounding
+        whitespace); must not be null
+    @param text
+        the text to add
+*/
 TOOLS_DLLPUBLIC void appendUnixShellWord(
     rtl::OStringBuffer * accumulator, rtl::OString const & text);
 
diff --git a/tools/inc/tools/b3dtrans.hxx b/tools/inc/tools/b3dtrans.hxx
index a44916d70019..ebf61e877942 100644
--- a/tools/inc/tools/b3dtrans.hxx
+++ b/tools/inc/tools/b3dtrans.hxx
@@ -29,9 +29,7 @@
 #include <basegfx/point/b2dpoint.hxx>
 #include <tools/toolsdllapi.h>
 
-
-// Supported methods for setting/keeping the aspect ratio
-
+/// Supported methods for setting the aspect ratio
 enum Base3DRatio
 {
     Base3DRatioGrow = 1,
@@ -39,16 +37,14 @@ enum Base3DRatio
     Base3DRatioMiddle
 };
 
-// Supported projection types
-
+/// Supported projection types
 enum Base3DProjectionType
 {
     Base3DProjectionTypeParallel = 1,
     Base3DProjectionTypePerspective
 };
 
-// Transformation sets for 3D output
-
+/// Transformation sets for 3D output
 class TOOLS_DLLPUBLIC B3dTransformationSet
 {
 private:
@@ -188,13 +184,11 @@ protected:
     virtual void DeviceRectangleChange();
 };
 
-/*************************************************************************
-|* Viewport for B3D
-|*
-|* Uses a simplified model, in which a point
-|* is described using a View Reference Point (VRP)
-\************************************************************************/
+/** Viewport for B3D
 
+    Uses a simplified model, in which a point is described using a View
+    Reference Point (VRP).
+*/
 class TOOLS_DLLPUBLIC B3dViewport : public B3dTransformationSet
 {
 private:
diff --git a/tools/inc/tools/inetstrm.hxx b/tools/inc/tools/inetstrm.hxx
index 3a0665620ad1..dd3e430597a8 100644
--- a/tools/inc/tools/inetstrm.hxx
+++ b/tools/inc/tools/inetstrm.hxx
@@ -96,9 +96,7 @@ enum INetMessageStreamState
     INETMSG_EOL_FESC
 };
 
-/*
- * INetMessageIStream (Message Generator) Interface.
- */
+/// Message Generator Interface.
 class INetMessageIStream : public INetIStream
 {
     INetMessage    *pSourceMsg;
@@ -134,9 +132,7 @@ public:
     sal_Bool IsHeaderGenerated (void) const { return bHeaderGenerated; }
 };
 
-/*
- * INetMessageOStream (Message Parser) Interface.
- */
+/// Message Parser Interface.
 class INetMessageOStream : public INetOStream
 {
     INetMessage            *pTargetMsg;
diff --git a/tools/inc/tools/pathutils.hxx b/tools/inc/tools/pathutils.hxx
index 80b67b611c0d..d7e4e89f576e 100644
--- a/tools/inc/tools/pathutils.hxx
+++ b/tools/inc/tools/pathutils.hxx
@@ -35,55 +35,52 @@
 
 namespace tools {
 
-// Determine the filename part of a path.
-//
-// @param path
-// A non-NULL pointer to a null-terminated path.
-//
-// @return
-// A pointer to the trailing filename part of the given path.
+/** Determine the filename part of a path.
+    @param path
+        A non-NULL pointer to a null-terminated path.
+    @return
+        A pointer to the trailing filename part of the given path.
+*/
 WCHAR * filename(WCHAR * path);
 
-// Concatenate two paths.
-//
-// Either the first path is empty and the second path is an absolute path.  Or
-// the first path is an absolute path that ends in a backslash and the second
-// path is a relative path.  In the latter case, to avoid paths that grow too
-// long, leading .. segments of the second path are removed together with
-// trailing segments from the first path.  This should not cause problems as
-// long as there are no symbolic links on Windows (as with symbolic links,
-// x\y\.. and x might denote different directories).
-//
-// @param path
-// An output paremeter taking the resulting path; must point at a valid range of
-// memory of size at least MAX_PATH.  If NULL is returned, the content is
-// unspecified.
-//
-// @param frontBegin, frontEnd
-// Forms a valid range [frontBegin .. frontEnd) of less than MAX_PATH size.
-//
-// @param backBegin, backLength
-// Forms a valid range [backBeghin .. backBegin + backLength) of less than
-// MAX_PATH size.
-//
-// @return
-// A pointer to the terminating null character of the concatenation, or NULL if
-// a failure occurred.
+/** Concatenate two paths.
+
+    Either the first path is empty and the second path is an absolute path. Or
+    the first path is an absolute path that ends in a backslash and the second
+    path is a relative path.  In the latter case, to avoid paths that grow too
+    long, leading .. segments of the second path are removed together with
+    trailing segments from the first path. This should not cause problems as long
+    as there are no symbolic links on Windows (as with symbolic links, x\y\.. and
+    x might denote different directories).
+
+    @param path
+        An output paremeter taking the resulting path; must point at a valid
+        range of memory of size at least MAX_PATH.  If NULL is returned, the
+        content is unspecified.
+    @param frontBegin, frontEnd
+        Forms a valid range [frontBegin .. frontEnd) of less than MAX_PATH size.
+    @param backBegin, backLength
+        Forms a valid range [backBeghin .. backBegin + backLength) of less than
+        MAX_PATH size.
+    @return
+        A pointer to the terminating null character of the concatenation, or NULL
+        if a failure occurred.
+*/
 WCHAR * buildPath(
     WCHAR * path, WCHAR const * frontBegin, WCHAR const * frontEnd,
     WCHAR const * backBegin, std::size_t backLength);
 
-// Resolve a link file.
-//
-// @param path
-// An input/output parameter taking the path; must point at a valid range of
-// memory of size at least MAX_PATH.  On input, contains the null-terminated
-// full path of the link file.  On output, contains the null-terminated full
-// path of the resolved link; if NULL is returned, the content is unspecified.
-//
-// @return
-// A pointer to the terminating null character of path, or NULL if a failure
-// occurred.
+/** Resolve a link file.
+
+    @param path
+        An input/output parameter taking the path; must point at a valid range of
+        memory of size at least MAX_PATH.  On input, contains the null-terminated
+        full path of the link file.  On output, contains the null-terminated full
+        path of the resolved link; if NULL is returned, the content is unspecified.
+    @return
+        A pointer to the terminating null character of path, or NULL if a failure
+        occurred.
+*/
 WCHAR * resolveLink(WCHAR * path);
 
 }
diff --git a/tools/inc/tools/resid.hxx b/tools/inc/tools/resid.hxx
index 1dc89d2492eb..cbe4ed25c622 100644
--- a/tools/inc/tools/resid.hxx
+++ b/tools/inc/tools/resid.hxx
@@ -88,9 +88,8 @@ class ResId
     { m_nWinBits = nBits; }
 
     RESOURCE_TYPE   GetRT() const { return( m_nRT ); }
-    const ResId &   SetRT( RESOURCE_TYPE nType ) const
-    /*
-    Set the type if not already set. Ask for tye with GetRT()
+
+    /** Set the type if not already set. Ask for tye with GetRT()
 
     [Example]
     ResId aId( 1000 );
@@ -101,28 +100,29 @@ class ResId
     @see
     ResId::GetRT2(), ResId::GetRT()
     */
+    const ResId &   SetRT( RESOURCE_TYPE nType ) const
     {
         if( RSC_NOTYPE == m_nRT )
             m_nRT = nType;
         return *this;
     }
-    RESOURCE_TYPE   GetRT2() const
-    /*
-    Get the effective type (m_nRT2 or m_nRT1)
+
+    /** Get the effective type (m_nRT2 or m_nRT1)
 
     A second resource type is used to supercede settings
     of the base class ( e.g. Window )
     */
+    RESOURCE_TYPE   GetRT2() const
     {
         return (RSC_NOTYPE == m_nRT2) ? m_nRT : m_nRT2;
     }
-    const ResId &   SetRT2( RESOURCE_TYPE nTyp ) const
-    /*
-    Set the superceding type. Ask spcifically for it with GetRT2()
+
+    /** Set the superceding type. Ask spcifically for it with GetRT2()
 
     SetRT2() may only be called if no derived class calls SetRT in its
     Resource constructor.
     */
+    const ResId &   SetRT2( RESOURCE_TYPE nTyp ) const
     {
         if( RSC_NOTYPE == m_nRT2 )
             m_nRT2 = nTyp;
diff --git a/tools/inc/tools/resmgr.hxx b/tools/inc/tools/resmgr.hxx
index 985365760f04..bdfd4661bd52 100644
--- a/tools/inc/tools/resmgr.hxx
+++ b/tools/inc/tools/resmgr.hxx
@@ -34,20 +34,20 @@ class InternalResMgr;
 // - RSHEADER_TYPE -
 // -----------------
 
-// Defines structure used to build resource
+/// Defines structure used to build resource
 struct RSHEADER_TYPE
 {
 private:
-    sal_uInt32              nId;        // Identifier of resource
-    RESOURCE_TYPE           nRT;        // Resource type
-    sal_uInt32              nGlobOff;   // Global offset
-    sal_uInt32              nLocalOff;  // Local offset
+    sal_uInt32              nId;        ///< Identifier of resource
+    RESOURCE_TYPE           nRT;        ///< Resource type
+    sal_uInt32              nGlobOff;   ///< Global offset
+    sal_uInt32              nLocalOff;  ///< Local offset
 
 public:
-    inline sal_uInt32       GetId();       // Identifier of resource
-    inline RESOURCE_TYPE    GetRT();       // Resource type
-    inline sal_uInt32       GetGlobOff();  // Global offset
-    inline sal_uInt32       GetLocalOff(); // Local offset
+    inline sal_uInt32       GetId();    ///< Identifier of resource
+    inline RESOURCE_TYPE    GetRT();    ///< Resource type
+    inline sal_uInt32       GetGlobOff();  ///< Global offset
+    inline sal_uInt32       GetLocalOff(); ///< Local offset
 };
 
 // ----------
@@ -74,13 +74,13 @@ class ResMgr;
 struct ImpRCStack
 {
     // pResource and pClassRes equal NULL: resource was not loaded
-    RSHEADER_TYPE * pResource;          // pointer to resource
-    void          * pClassRes;          // pointer to class specified init data
-    short           Flags;              // resource status
-    void *          aResHandle;         // Resource-Identifier from InternalResMgr
-    const Resource* pResObj;            // pointer to Resource object
-    sal_uInt32      nId;                // ResId used for error message
-    ResMgr*         pResMgr;            // ResMgr for Resource pResObj
+    RSHEADER_TYPE * pResource;  ///< pointer to resource
+    void          * pClassRes;  ///< pointer to class specified init data
+    short           Flags;      ///< resource status
+    void *          aResHandle; ///< Resource-Identifier from InternalResMgr
+    const Resource* pResObj;    ///< pointer to Resource object
+    sal_uInt32      nId;        ///< ResId used for error message
+    ResMgr*         pResMgr;    ///< ResMgr for Resource pResObj
 
     void            Clear();
     void            Init( ResMgr * pMgr, const Resource * pObj, sal_uInt32 nId );
@@ -89,13 +89,13 @@ struct ImpRCStack
 class TOOLS_DLLPUBLIC ResMgr
 {
 private:
-    InternalResMgr*            pImpRes;
-    std::vector< ImpRCStack >  aStack;  // resource context stack
-    int                        nCurStack;
-    ResMgr*         pFallbackResMgr;    // fallback ResMgr in case the Resource
-                                        // was not contained in this ResMgr
-    ResMgr*         pOriginalResMgr;    // the res mgr that fell back to this
-                                        // stack level
+    InternalResMgr* pImpRes;
+    std::vector< ImpRCStack >  aStack; ///< resource context stack
+    int             nCurStack;
+    ResMgr*         pFallbackResMgr;   ///< fallback ResMgr in case the Resource
+                                       ///< was not contained in this ResMgr
+    ResMgr*         pOriginalResMgr;   ///< the res mgr that fell back to this
+                                       ///< stack level
 
     TOOLS_DLLPRIVATE void         incStack();
     TOOLS_DLLPRIVATE void         decStack();
@@ -134,12 +134,12 @@ private:
     ResMgr(const ResMgr&);
     ResMgr& operator=(const ResMgr&);
 public:
-    static void         DestroyAllResMgr();  // Called upon app shutdown
+    static void         DestroyAllResMgr();  ///< Called upon app shutdown
 
     ~ResMgr();
 
-    // Language-dependent resource library
-    static const sal_Char*  GetLang( LanguageType& eLanguage, sal_uInt16 nPrio = 0 ); //depricated! see "tools/source/rc/resmgr.cxx"
+    /// Language-dependent resource library
+    static const sal_Char*  GetLang( LanguageType& eLanguage, sal_uInt16 nPrio = 0 ); ///< @deprecated see "tools/source/rc/resmgr.cxx"
     static ResMgr*      SearchCreateResMgr( const sal_Char* pPrefixName,
                                             com::sun::star::lang::Locale& rLocale );
      static ResMgr*     CreateResMgr( const sal_Char* pPrefixName,
@@ -147,44 +147,44 @@ public:
                                                                                                            rtl::OUString(),
                                                                                                            rtl::OUString()));
 
-    // Test whether resource still exists
+    /// Test whether resource still exists
     void                TestStack( const Resource * );
 
-    // Returns whether resource is available
+    /// Check whether resource is available
     sal_Bool                IsAvailable( const ResId& rId,
                                      const Resource* = NULL) const;
 
-    // Search and load resource, given its ID
+    /// Search and load resource, given its ID
     sal_Bool                GetResource( const ResId& rId, const Resource * = NULL );
     static void *       GetResourceSkipHeader( const ResId& rResId, ResMgr ** ppResMgr );
-    // Free resource context
+    /// Free resource context
     void                PopContext( const Resource* = NULL );
 
-    // Increment resource pointer
+    /// Incremet resource pointer
     void*               Increment( sal_uInt32 nSize );
 
-    // Size of an object within the resource
+    /// Size of an object within the resource
     static sal_uInt32   GetObjSize( RSHEADER_TYPE* pHT )
                             { return( pHT->GetGlobOff() ); }
 
-    // returns a string and its length out of the resource
+    /// Return a string and its length out of the resource
     static sal_uInt32   GetString( UniString& rStr, const sal_uInt8* pStr );
-    // returns a byte string and its length out of the resource
+    /// Return a byte string and its length out of the resource
     static sal_uInt32   GetByteString( rtl::OString& rStr, const sal_uInt8* pStr );
 
-    // returns the size of a string in the resource
+    /// Return the size of a string in the resource
     static sal_uInt32   GetStringSize( sal_uInt32 nLen )
                             { nLen++; return (nLen + nLen%2); }
     static sal_uInt32   GetStringSize( const sal_uInt8* pStr, sal_uInt32& nLen );
 
-    // return a int64
+    /// Return a int64
     static sal_uInt64   GetUInt64( void* pDatum );
-    // return a long
+    /// Return a long
     static sal_Int32        GetLong( void * pLong );
-    // return a short
+    /// Return a short
     static sal_Int16        GetShort( void * pShort );
 
-    // return a pointer to the resource
+    /// Return a pointer to the resource
     void *              GetClass();
 
     RSHEADER_TYPE *     CreateBlock( const ResId & rId );
@@ -198,7 +198,7 @@ public:
     UniString           ReadString();
     rtl::OString        ReadByteString();
 
-    // generate auto help id for current resource stack
+    /// Generate auto help ID for current resource stack
     rtl::OString        GetAutoHelpId();
 
     static void         SetReadStringHook( ResHookProc pProc );
diff --git a/tools/inc/tools/rtti.hxx b/tools/inc/tools/rtti.hxx
index cb3abec0ba11..8039aa3cf9eb 100644
--- a/tools/inc/tools/rtti.hxx
+++ b/tools/inc/tools/rtti.hxx
@@ -105,24 +105,24 @@ typedef void* (*TypeId)();
 
 //-------------------------------------------------------------------------
 
-//      Exemplary application macros for pointers
-//      (can be extended for use with references)
-//
-//      PTR_CAST: Safe pointer casting to a derived class.
-//      Returns NULL pointer on cast error.
-//
-//      T: Target type to cast into
-//      p: Pointer to be cast into T
+/** Exemplary application macros for pointers
+    (can be extended for use with references)
+
+    PTR_CAST: Safe pointer casting to a derived class.
+              Returns NULL pointer on cast error
+
+    T: Target type to cast into
+    p: Pointer to be cast into T
+*/
 #define PTR_CAST( T, pObj ) \
         ( pObj && (pObj)->IsA( TYPE(T) ) ? (T*)(pObj) : 0 )
 
-//      Check whether object pObj has a Base Class T
-//      (or if pObj is an instance of T)
+/** Check whether object pObj has a Base Class T
+    (or if pObj is an instance of T) */
 #define HAS_BASE( T, pObj ) \
         ( pObj && (pObj)->IsA( TYPE(T) ) )
 
-//      Check whether a pointer is targetting
-//      an object of type T.
+/** Check whether a pointer is targetting and object of type T. */
 #define IS_TYPE(T,pObj) \
         ( pObj && (pObj)->Type() == TYPE(T) )
 
diff --git a/tools/inc/tools/solar.h b/tools/inc/tools/solar.h
index 239599e1b2fe..5820e1b9b679 100644
--- a/tools/inc/tools/solar.h
+++ b/tools/inc/tools/solar.h
@@ -31,13 +31,11 @@
 #endif
 #define _SOLAR__PRIVATE 1
 
-/************************************************************
- Intermediate type to solve type clash with Windows headers.
+/** Intermediate type to solve type clash with Windows headers.
  Should be removed as soon as all code parts have been reviewed
  and the correct type is known. Most of the times ULONG is meant
  to be a 32-Bit unsigned integer type as sal_uInt32 is often
- used for data exchange or for similiar method args.
-*************************************************************/
+ used for data exchange or for similiar method args. */
 typedef sal_uIntPtr    sal_uLong; /* Replaces type ULONG */
 
 /*** misc. macros to leverage platform and compiler differences ********/
diff --git a/tools/inc/tools/stream.hxx b/tools/inc/tools/stream.hxx
index dafcfc342cfa..d237d091ed14 100644
--- a/tools/inc/tools/stream.hxx
+++ b/tools/inc/tools/stream.hxx
@@ -50,12 +50,12 @@ inline rtl_TextEncoding GetStoreCharSet( rtl_TextEncoding eEncoding )
 typedef sal_uInt16 StreamMode;
 
 // read, write, create,... options
-#define STREAM_READ                     0x0001  // allow read accesses
-#define STREAM_WRITE                    0x0002  // allow write accesses
+#define STREAM_READ                     0x0001  ///< allow read accesses
+#define STREAM_WRITE                    0x0002  ///< allow write accesses
 // file i/o
-#define STREAM_NOCREATE                 0x0004  // 1 == Dont create file
-#define STREAM_TRUNC                    0x0008  // Truncate _existing_ file to zero length
-#define STREAM_COPY_ON_SYMLINK          0x0010  // copy-on-write for symlinks (UNX)
+#define STREAM_NOCREATE                 0x0004  ///< 1 == Dont create file
+#define STREAM_TRUNC                    0x0008  ///< Truncate _existing_ file to zero length
+#define STREAM_COPY_ON_SYMLINK          0x0010  ///< copy-on-write for symlinks (UNX)
 
 #define STREAM_READWRITEBITS            (STREAM_READ | STREAM_WRITE | \
                                          STREAM_NOCREATE | STREAM_TRUNC)
@@ -270,7 +270,7 @@ private:
     SvStream&       operator=( const SvStream& rStream ); // not implemented
 
 protected:
-    sal_Size            nBufFilePos;    // File position of pBuf[0]
+    sal_Size            nBufFilePos;    ///< File position of pBuf[0]
     sal_uInt16          eStreamMode;
     sal_Bool            bIsWritable;
 
@@ -287,8 +287,8 @@ protected:
     sal_Size            CryptAndWriteBuffer( const void* pStart, sal_Size nLen );
     sal_Bool            EncryptBuffer( void* pStart, sal_Size nLen );
 
-    void            SyncSvStream( sal_Size nNewStreamPos ); // SvStream <- Medium
-    void            SyncSysStream(); // SvStream -> Medium
+    void            SyncSvStream( sal_Size nNewStreamPos ); ///< SvStream <- Medium
+    void            SyncSysStream(); ///< SvStream -> Medium
 
 public:
                     SvStream();
@@ -307,7 +307,7 @@ public:
     sal_uInt16          GetNumberFormatInt() const { return nNumberFormatInt; }
                     /// Enable/disable swapping of endians, may be needed for Unicode import/export
     inline void     SetEndianSwap( sal_Bool bVal );
-                    // returns status of endian swap flag
+    /// returns status of endian swap flag
     sal_Bool            IsEndianSwap() const { return 0 != bSwap; }
 
     void            SetCompressMode( sal_uInt16 nNewMode )
@@ -528,26 +528,26 @@ TOOLS_DLLPUBLIC SvStream& endlu( SvStream& rStr );
 /// call endlu() if eStreamCharSet==RTL_TEXTECODING_UNICODE otherwise endl()
 TOOLS_DLLPUBLIC SvStream& endlub( SvStream& rStr );
 
-//Attempt to read nUnits 8bit units to an OString, returned rtl::OString's
-//length is number of units successfully read
+/// Attempt to read nUnits 8bit units to an OString, returned rtl::OString's
+/// length is number of units successfully read
 TOOLS_DLLPUBLIC rtl::OString read_uInt8s_ToOString(SvStream& rStrm,
     sal_Size nUnits);
 
-//Attempt to read nUnits 8bit units to an OUString
+/// Attempt to read nUnits 8bit units to an OUString
 TOOLS_DLLPUBLIC inline rtl::OUString read_uInt8s_ToOUString(SvStream& rStrm,
     sal_Size nUnits, rtl_TextEncoding eEnc)
 {
     return rtl::OStringToOUString(read_uInt8s_ToOString(rStrm, nUnits), eEnc);
 }
 
-//Attempt to read nUnits 16bit units to an OUString, returned
-//rtl::OUString's length is number of units successfully read
+/// Attempt to read nUnits 16bit units to an OUString, returned
+/// rtl::OUString's length is number of units successfully read
 TOOLS_DLLPUBLIC rtl::OUString read_uInt16s_ToOUString(SvStream& rStrm,
     sal_Size nUnits);
 
-//Attempt to read a pascal-style length (of type prefix) prefixed sequence of
-//16bit units to an OUString, returned rtl::OString's length is number of units
-//successfully read.
+/// Attempt to read a pascal-style length (of type prefix) prefixed sequence of
+/// 16bit units to an OUString, returned rtl::OString's length is number of
+/// units successfully read.
 template<typename prefix>
 rtl::OUString read_lenPrefixed_uInt16s_ToOUString(SvStream& rStrm)
 {
@@ -556,8 +556,8 @@ rtl::OUString read_lenPrefixed_uInt16s_ToOUString(SvStream& rStrm)
     return read_uInt16s_ToOUString(rStrm, nUnits);
 }
 
-//Attempt to write a prefixed sequence of nUnits 16bit units from an OUString,
-//returned value is number of bytes written
+/// Attempt to write a prefixed sequence of nUnits 16bit units from an OUString,
+/// returned value is number of bytes written
 TOOLS_DLLPUBLIC sal_Size write_uInt16s_FromOUString(SvStream& rStrm,
     const rtl::OUString& rStr, sal_Size nUnits);
 
@@ -569,9 +569,9 @@ TOOLS_DLLPUBLIC inline sal_Size write_uInt16s_FromOUString(SvStream& rStrm,
 
 namespace streamdetail
 {
-    //Attempt to write a pascal-style length (of type prefix) prefixed sequence of
-    //units from a string-type, returned value is number of bytes written (including
-    //byte-count of prefix)
+    /// Attempt to write a pascal-style length (of type prefix) prefixed
+    /// sequence of units from a string-type, returned value is number of bytes
+    /// written (including byte-count of prefix)
     template<typename prefix, typename S, sal_Size (*writeOper)(SvStream&, const S&, sal_Size)>
         sal_Size write_lenPrefixed_seq_From_str(SvStream& rStrm, const S &rStr)
     {
@@ -590,29 +590,29 @@ namespace streamdetail
     }
 }
 
-//Attempt to write a pascal-style length (of type prefix) prefixed sequence of
-//16bit units from an OUString, returned value is number of bytes written (including
-//byte-count of prefix)
+/// Attempt to write a pascal-style length (of type prefix) prefixed sequence
+/// of 16bit units from an OUString, returned value is number of bytes written
+/// (including byte-count of prefix)
 template<typename prefix> sal_Size write_lenPrefixed_uInt16s_FromOUString(SvStream& rStrm,
     const rtl::OUString &rStr)
 {
     return streamdetail::write_lenPrefixed_seq_From_str<prefix, rtl::OUString, write_uInt16s_FromOUString>(rStrm, rStr);
 }
 
-//Attempt to read 8bit units to an OString until a zero terminator is
-//encountered, returned rtl::OString's length is number of units *definitely*
-//successfully read, check SvStream::good() to see if null terminator was
-//sucessfully read
+/// Attempt to read 8bit units to an OString until a zero terminator is
+/// encountered, returned rtl::OString's length is number of units *definitely*
+/// successfully read, check SvStream::good() to see if null terminator was
+/// sucessfully read
 TOOLS_DLLPUBLIC rtl::OString read_zeroTerminated_uInt8s_ToOString(SvStream& rStrm);
 
-//Attempt to read 8bit units assuming source encoding eEnc to an OUString until
-//a zero terminator is encountered. Check SvStream::good() to see if null
-//terminator was sucessfully read
+/// Attempt to read 8bit units assuming source encoding eEnc to an OUString
+/// until a zero terminator is encountered. Check SvStream::good() to see if
+/// null terminator was sucessfully read
 TOOLS_DLLPUBLIC rtl::OUString read_zeroTerminated_uInt8s_ToOUString(SvStream& rStrm, rtl_TextEncoding eEnc);
 
-//Attempt to read a pascal-style length (of type prefix) prefixed sequence of
-//8bit units to an OString, returned rtl::OString's length is number of units
-//successfully read.
+/// Attempt to read a pascal-style length (of type prefix) prefixed sequence of
+/// 8bit units to an OString, returned rtl::OString's length is number of units
+/// successfully read.
 template<typename prefix>
 rtl::OString read_lenPrefixed_uInt8s_ToOString(SvStream& rStrm)
 {
@@ -621,8 +621,8 @@ rtl::OString read_lenPrefixed_uInt8s_ToOString(SvStream& rStrm)
     return read_uInt8s_ToOString(rStrm, nUnits);
 }
 
-//Attempt to read a pascal-style length (of type prefix) prefixed sequence of
-//8bit units to an OUString
+/// Attempt to read a pascal-style length (of type prefix) prefixed sequence of
+/// 8bit units to an OUString
 template<typename prefix>
 rtl::OUString read_lenPrefixed_uInt8s_ToOUString(SvStream& rStrm,
     rtl_TextEncoding eEnc)
@@ -630,8 +630,8 @@ rtl::OUString read_lenPrefixed_uInt8s_ToOUString(SvStream& rStrm,
     return rtl::OStringToOUString(read_lenPrefixed_uInt8s_ToOString<prefix>(rStrm), eEnc);
 }
 
-//Attempt to write a prefixed sequence of nUnits 8bit units from an OString,
-//returned value is number of bytes written
+/// Attempt to write a prefixed sequence of nUnits 8bit units from an OString,
+/// returned value is number of bytes written
 TOOLS_DLLPUBLIC inline sal_Size write_uInt8s_FromOString(SvStream& rStrm, const rtl::OString& rStr,
     sal_Size nUnits)
 {
@@ -736,21 +736,20 @@ protected:
     virtual void    SetSize( sal_Size nSize );
     virtual void    FlushData();
 
-    // AllocateMemory must update pBuf accordingly
-    // - pBuf: Address of new block
-    virtual sal_Bool    AllocateMemory( sal_Size nSize );
-
-    // ReAllocateMemory must update the following variables:
-    // - pBuf: Address of new block
-    // - nEndOfData: Set to nNewSize-1L if outside of block
-    //               Set to 0 if new block size is 0 bytes
-    // - nSize: New block size
-    // - nPos: Set to 0 if position outside of block
-    virtual sal_Bool    ReAllocateMemory( long nDiff );
-
-    // is called when this stream allocated the buffer
-    // or the buffer is resized.
-    // FreeMemory may need to NULL handles in derived classes
+    /// AllocateMemory must update pBuf accordingly
+    /// - pBuf: Address of new block
+    virtual sal_Bool AllocateMemory( sal_Size nSize );
+
+    /// ReAllocateMemory must update the following variables:
+    /// - pBuf: Address of new block
+    /// - nEndOfData: Set to nNewSize-1L , if outside of block
+    ///               Set to 0 , if new block size is 0 bytes
+    /// - nSize: New block size
+    /// - nPos: Set to 0 if position outside of block
+    virtual sal_Bool ReAllocateMemory( long nDiff );
+
+    /// Is called when this stream allocated the buffer or the buffer is
+    /// resized. FreeMemory may need to NULLify handles in derived classes.
     virtual void    FreeMemory();
 
                     SvMemoryStream(void*) { }   // for sub-classes
@@ -778,13 +777,11 @@ public:
     virtual sal_Size remainingSize() { return GetSize() - Tell(); }
 };
 
-// --------------------
-// - SvDataCopyStream -
-// --------------------
-
-// This class is the foundation for all classes that use SvData for
-// transportation (e.g., graphics).
+/** Data Copy Stream
 
+    This class is the foundation for all classes, using SvData
+    (SO2\DTRANS.HXX/CXX) for transportation (e.g., graphics).
+*/
 class TOOLS_DLLPUBLIC SvDataCopyStream
 {
 public:
diff --git a/tools/inc/tools/tempfile.hxx b/tools/inc/tools/tempfile.hxx
index 520c9a132824..376de44c29c2 100644
--- a/tools/inc/tools/tempfile.hxx
+++ b/tools/inc/tools/tempfile.hxx
@@ -29,32 +29,38 @@ class TOOLS_DLLPUBLIC TempFile
     sal_Bool        bKillingFileEnabled;
 
 public:
-                    // Create a temporary file or directory in a given folder or the default tempfile folder
+    /** Create a temporary file or directory in a given folder or the default
+        tempfile folder. */
                     TempFile( const String* pParent=NULL, sal_Bool bDirectory=sal_False );
 
-                    // Create a temporary file or directory in a given folder or the default tempfile folder; its name starts
-                    // with some given characters followed by a counter ( example: rLeadingChars="abc" means "abc0","abc1"
-                    // and so on, depending on existing files in that folder ).
-                    // The extension string may be f.e. ".txt" or "", if no extension string is given, ".tmp" is used
+    /** Create a temporary file or directory in a given folder or the default
+        tempfile folder; its name starts with some given characters followed by
+        a counter ( example: rLeadingChars="abc" means "abc0","abc1" and so on,
+        depending on existing files in that folder ).
+
+        The extension string may be f.e. ".txt" or "", if no extension string is
+        given, ".tmp" is used.
+    */
                     TempFile( const String& rLeadingChars, const String* pExtension=NULL, const String* pParent=NULL, sal_Bool bDirectory=sal_False );
 
-                    // TempFile will be removed from disk in dtor if EnableKillingTempFile was called before.
-                    // TempDirs will be removed recursively in that case.
+    /** TempFile will be removed from disk in dtor if EnableKillingTempFile was
+        called before. TempDirs will be removed recursively in that case. */
                     ~TempFile();
 
     sal_Bool        IsValid() const;
 
-                    // Returns the real name of the tempfile in file URL scheme.
+    /** Returns the real name of the tempfile in file URL scheme. */
     String          GetName() const;
 
-                    // If enabled the file will be removed from disk when the dtor is called ( default is not enabled )
+    /** If enabled the file will be removed from disk when the dtor is called
+        (default is not enabled) */
     void            EnableKillingFile( sal_Bool bEnable=sal_True )
                     { bKillingFileEnabled = bEnable; }
 
     sal_Bool        IsKillingFileEnabled() const
                     { return bKillingFileEnabled; }
 
-                    // Only create a name for a temporary file that would be valid at that moment.
+    /** Only create a name for a temporary file that would be valid at that moment. */
     static String   CreateTempName( const String* pParent=NULL );
 };
 
diff --git a/tools/inc/tools/tenccvt.hxx b/tools/inc/tools/tenccvt.hxx
index 5b99bdf69a9d..ca72f7e1948e 100644
--- a/tools/inc/tools/tenccvt.hxx
+++ b/tools/inc/tools/tenccvt.hxx
@@ -26,25 +26,25 @@
 // - Functions for handling Import/Export -
 // ----------------------------------------
 
-// return an encoding which has more defined Characters as the given
-// encoding, but have the same definition for the defined characters
-// e.g.: windows-1252 for iso-8859-1 or windows-1254 for iso-8859-9
+/// return an encoding which has more defined Characters as the given
+/// encoding, but have the same definition for the defined characters
+/// e.g.: windows-1252 for iso-8859-1 or windows-1254 for iso-8859-9
 TOOLS_DLLPUBLIC rtl_TextEncoding GetExtendedCompatibilityTextEncoding( rtl_TextEncoding eEncoding );
 
-// return an encoding which has more defined Characters as the given
-// encoding. The encodings could be different.
-// e.g.: windows-1251 for iso-8859-5
+/// return an encoding which has more defined Characters as the given
+/// encoding. The encodings could be different.
+/// e.g.: windows-1251 for iso-8859-5
 TOOLS_DLLPUBLIC rtl_TextEncoding GetExtendedTextEncoding( rtl_TextEncoding eEncoding );
 
-// if the given encoding is an multi-byte encoding (which allows more than
-// one byte per char, e.g. UTF-8 or Shift-JIS), a one-byte encoding
-// is returned (normally windows-1252).
+/// if the given encoding is an multi-byte encoding (which allows more than
+/// one byte per char, e.g. UTF-8 or Shift-JIS), a one-byte encoding
+/// is returned (normally windows-1252).
 TOOLS_DLLPUBLIC rtl_TextEncoding GetOneByteTextEncoding( rtl_TextEncoding eEncoding );
 
 TOOLS_DLLPUBLIC rtl_TextEncoding GetSOLoadTextEncoding( rtl_TextEncoding eEncoding );
 TOOLS_DLLPUBLIC rtl_TextEncoding GetSOStoreTextEncoding( rtl_TextEncoding eEncoding );
 
-/*
+/**
  * Given a Unicode character, return a legacy Microsoft Encoding which
  * supports it. Returns RTL_TEXTENCODING_DONTKNOW if there is
  * no encoding which could support the character