diff options
author | Philipp Riemer <ruderphilipp@gmail.com> | 2012-08-13 22:21:56 +0200 |
---|---|---|
committer | Philipp Riemer <ruderphilipp@gmail.com> | 2012-08-13 23:52:36 +0200 |
commit | 7dfba55bfd15b3c3b080a13b63073e6d2ab808b7 (patch) | |
tree | 61d90e762ffbea2da0cd853059eb73d2ae30d248 /tools | |
parent | installer::download: Clean up get_versionstring and make private (diff) | |
download | core-7dfba55bfd15b3c3b080a13b63073e6d2ab808b7.tar.gz core-7dfba55bfd15b3c3b080a13b63073e6d2ab808b7.zip |
"doxygenized" comments in tools/inc
This is a follow-up patch to c8b7aa55138848fe07108779099267424bc03e3d.
Change-Id: I124d01ff13d12ea392e6ef283a585d63b1b82e1e
Diffstat (limited to 'tools')
-rw-r--r-- | tools/inc/bootstrp/prj.hxx | 7 | ||||
-rw-r--r-- | tools/inc/impcont.hxx | 46 | ||||
-rw-r--r-- | tools/inc/tools/appendunixshellword.hxx | 16 | ||||
-rw-r--r-- | tools/inc/tools/b3dtrans.hxx | 20 | ||||
-rw-r--r-- | tools/inc/tools/inetstrm.hxx | 8 | ||||
-rw-r--r-- | tools/inc/tools/pathutils.hxx | 83 | ||||
-rw-r--r-- | tools/inc/tools/resid.hxx | 18 | ||||
-rw-r--r-- | tools/inc/tools/resmgr.hxx | 80 | ||||
-rw-r--r-- | tools/inc/tools/rtti.hxx | 24 | ||||
-rw-r--r-- | tools/inc/tools/solar.h | 6 | ||||
-rw-r--r-- | tools/inc/tools/stream.hxx | 117 | ||||
-rw-r--r-- | tools/inc/tools/tempfile.hxx | 26 | ||||
-rw-r--r-- | tools/inc/tools/tenccvt.hxx | 20 |
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 |