diff options
author | Peter Foley <pefoley2@verizon.net> | 2013-03-18 21:55:24 -0400 |
---|---|---|
committer | Peter Foley <pefoley2@verizon.net> | 2013-03-18 21:57:02 -0400 |
commit | 980c1179bbde47bab53410794795781d0e61e82a (patch) | |
tree | 2c92e8a6ddce8f75bd32211484223accac16e4c0 /sal | |
parent | cleanup autodoc output (diff) | |
download | core-980c1179bbde47bab53410794795781d0e61e82a.tar.gz core-980c1179bbde47bab53410794795781d0e61e82a.zip |
cleanup doxygen warnings
Change-Id: I9181cad5bfa93f9e8b3d944b2b50a3ccc0b42595
Diffstat (limited to 'sal')
-rw-r--r-- | sal/inc/osl/file.hxx | 2 | ||||
-rw-r--r-- | sal/inc/osl/mutex.hxx | 12 | ||||
-rw-r--r-- | sal/inc/osl/security_decl.hxx | 4 | ||||
-rw-r--r-- | sal/inc/osl/socket.h | 31 | ||||
-rw-r--r-- | sal/inc/osl/socket_decl.hxx | 9 | ||||
-rw-r--r-- | sal/inc/rtl/alloc.h | 11 | ||||
-rw-r--r-- | sal/inc/rtl/bootstrap.h | 6 | ||||
-rw-r--r-- | sal/inc/rtl/cipher.h | 10 | ||||
-rw-r--r-- | sal/inc/rtl/crc.h | 3 | ||||
-rw-r--r-- | sal/inc/rtl/digest.h | 44 | ||||
-rw-r--r-- | sal/inc/rtl/logfile.hxx | 6 | ||||
-rw-r--r-- | sal/inc/rtl/strbuf.h | 29 | ||||
-rw-r--r-- | sal/inc/rtl/strbuf.hxx | 4 | ||||
-rw-r--r-- | sal/inc/rtl/string.h | 14 | ||||
-rw-r--r-- | sal/inc/rtl/uri.h | 30 | ||||
-rw-r--r-- | sal/inc/rtl/ustrbuf.h | 16 | ||||
-rw-r--r-- | sal/inc/rtl/ustrbuf.hxx | 2 | ||||
-rw-r--r-- | sal/inc/rtl/ustring.h | 13 | ||||
-rw-r--r-- | sal/inc/sal/log.hxx | 8 |
19 files changed, 153 insertions, 101 deletions
diff --git a/sal/inc/osl/file.hxx b/sal/inc/osl/file.hxx index e2e304f3e527..ee52cd570840 100644 --- a/sal/inc/osl/file.hxx +++ b/sal/inc/osl/file.hxx @@ -282,7 +282,6 @@ public: If pustrTempFileURL is not 0 the caller receives the name of the created file and is responsible for removing the file. - @descr Description of the different pHandle, ppustrTempFileURL parameter combinations. pHandle is 0 and pustrTempDirURL is 0 - this combination is invalid<br> pHandle is not 0 and pustrTempDirURL is 0 - a handle to the open file @@ -1256,7 +1255,6 @@ public: <dd>On success</dd> <dt>E_INVAL</dt> <dd>The value of the input parameter is invalid</dd> - </dl> <br><p><strong>In addition to these error codes others may occur as well, for instance:</strong></p><br> <dt>E_BADF</dt> <dd>The file is not open for writing</dd> diff --git a/sal/inc/osl/mutex.hxx b/sal/inc/osl/mutex.hxx index 9ed68612dc38..18ff44444223 100644 --- a/sal/inc/osl/mutex.hxx +++ b/sal/inc/osl/mutex.hxx @@ -34,7 +34,7 @@ namespace osl public: /** Create a thread-local mutex. @return 0 if the mutex could not be created, otherwise a handle to the mutex. - @seealso ::osl_createMutex() + @see ::osl_createMutex() */ Mutex() { @@ -42,7 +42,7 @@ namespace osl } /** Release the OS-structures and free mutex data-structure. - @seealso ::osl_destroyMutex() + @see ::osl_destroyMutex() */ ~Mutex() { @@ -51,7 +51,7 @@ namespace osl /** Acquire the mutex, block if already acquired by another thread. @return sal_False if system-call fails. - @seealso ::osl_acquireMutex() + @see ::osl_acquireMutex() */ sal_Bool acquire() { @@ -60,7 +60,7 @@ namespace osl /** Try to acquire the mutex without blocking. @return sal_False if it could not be acquired. - @seealso ::osl_tryToAcquireMutex() + @see ::osl_tryToAcquireMutex() */ sal_Bool tryToAcquire() { @@ -69,7 +69,7 @@ namespace osl /** Release the mutex. @return sal_False if system-call fails. - @seealso ::osl_releaseMutex() + @see ::osl_releaseMutex() */ sal_Bool release() { @@ -80,7 +80,7 @@ namespace osl The global and static mutex object can be used to initialize other static objects in a thread safe manner. @return the global mutex object - @seealso ::osl_getGlobalMutex() + @see ::osl_getGlobalMutex() */ static Mutex * getGlobalMutex() { diff --git a/sal/inc/osl/security_decl.hxx b/sal/inc/osl/security_decl.hxx index 0ac9276b9c0d..5b8b17066d91 100644 --- a/sal/inc/osl/security_decl.hxx +++ b/sal/inc/osl/security_decl.hxx @@ -51,12 +51,16 @@ public: inline sal_Bool SAL_CALL logonUser(const rtl::OUString& strName, const rtl::OUString& strPasswd); /** get the security information for one user. + + @verbatim This method will try to login the user at the denoted file server. If a network resource named \\server\username exists and this resource could be connected by this user, the methos will return true and getHomeDir will return \\server\username. + @endverbatim @param[in] strName denotes the name of the user @param[in] strPasswd denotes the password of this user + @param[in] strFileServer denotes the file server to login to @return True, if the specified user is known by file server and the could be connected, otherwise False */ diff --git a/sal/inc/osl/socket.h b/sal/inc/osl/socket.h index 385c4c3c9c09..ce47c8673beb 100644 --- a/sal/inc/osl/socket.h +++ b/sal/inc/osl/socket.h @@ -283,6 +283,7 @@ SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_getInetPortOfSocketAddr( /** Sets the Port of Addr. + @param[in] Addr the SocketAddr to perfom the operation on. @param[in] Port is expected in host byte-order. @return <code>sal_False</code> if Addr is not an inet-addr. */ @@ -291,7 +292,8 @@ SAL_DLLPUBLIC sal_Bool SAL_CALL osl_setInetPortOfSocketAddr( /** Returns the hostname represented by Addr. - @param strHostname out-parameter. The hostname represented by the address. If + @param[in] Addr The socket address from which to extract the hostname. + @param[out] strHostname The hostname represented by the address. If there is no hostname to be found, it returns 0. */ SAL_DLLPUBLIC oslSocketResult SAL_CALL osl_getHostnameOfSocketAddr( @@ -299,7 +301,8 @@ SAL_DLLPUBLIC oslSocketResult SAL_CALL osl_getHostnameOfSocketAddr( /** Gets the address in dotted decimal format. - @param strDottedInetAddr out-parameter. Contains the dotted decimal address + @param[in] Addr The socket address from which to extract the dotted decimal address. + @param[out] strDottedInetAddr Contains the dotted decimal address (e.g. 141.99.20.34) represented by the address. If the address is invalid or not of type <code>osl_Socket_FamilyInet</code>, it returns 0. @@ -314,7 +317,8 @@ SAL_DLLPUBLIC oslSocketResult SAL_CALL osl_setAddrOfSocketAddr( oslSocketAddr Addr, sal_Sequence *pByteSeq ); /** Returns the addr field in the struct sockaddr. - @param ppByteSeq out parameter. After the call, *ppByteSeq contains the ipadrress + @param[in] Addr The socket address from which to extract the ipaddress. + @param[out] ppByteSeq After the call, *ppByteSeq contains the ipaddress in network byteorder. *ppByteSeq may be 0 in case of an invalid socket handle. @return <code>osl_Socket_Ok</code> or <code>osl_Socket_Error</code> */ @@ -466,6 +470,7 @@ SAL_DLLPUBLIC oslSocketResult SAL_CALL osl_connectSocketTo( /** Prepares the socket to act as an acceptor of incoming connections. You should call "listen" before you use "accept". + @param[in] Socket The socket to listen on. @param[in] MaxPendingConnections denotes the length of the queue of pending connections for this socket. If MaxPendingConnections is -1, the systems default value will be used (Usually 5). @@ -478,6 +483,7 @@ SAL_DLLPUBLIC sal_Bool SAL_CALL osl_listenOnSocket( /** Waits for an ingoing connection on the socket. This call blocks if there is no incoming connection present. + @param[in] Socket The socket to accept the connection on. @param[in] pAddr if pAddr is != 0, the peers address is returned. @return 0 if the accept-call failed, otherwise you get a socket representing the new connection. @@ -637,7 +643,8 @@ SAL_DLLPUBLIC sal_Bool SAL_CALL osl_isExceptionPending( oslSocket Socket, const TimeValue* pTimeout); /** Shuts down communication on a connected socket. - @param Direction denotes which end of the socket + @param[in] Socket the Socket to perfom the operation on. + @param[in] Direction denotes which end of the socket should be closed: <ul> <li> <code>osl_Socket_DirRead</code> closes read operations. @@ -784,6 +791,7 @@ SAL_DLLPUBLIC sal_Bool SAL_CALL osl_isNonBlockingMode( /** Queries the socket for its type. + @param[in] Socket The socket to query. @return one of: <ul> <li> osl_Socket_TypeStream @@ -793,13 +801,13 @@ SAL_DLLPUBLIC sal_Bool SAL_CALL osl_isNonBlockingMode( <li> osl_Socket_TypeSeqPacket <li> osl_invalid_SocketType, if an error occurred </ul> - */ SAL_DLLPUBLIC oslSocketType SAL_CALL osl_getSocketType( oslSocket Socket); /** returns a string which describes the last socket error. - @param strError out-parameter. The string that receives the error message. + @param[in] Socket The socket to query. + @param[out] strError The string that receives the error message. */ SAL_DLLPUBLIC void SAL_CALL osl_getLastSocketErrorDescription( oslSocket Socket, rtl_uString **strError); @@ -871,14 +879,16 @@ SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_demultiplexSocketEvents(oslSocketSet Incomi const TimeValue* pTimeout); /** Closes the socket terminating any ongoing dataflow. + @param[in] Socket The socket to close. */ SAL_DLLPUBLIC void SAL_CALL osl_closeSocket(oslSocket Socket); /** Retrieves n bytes from the stream and copies them into pBuffer. The function avoids incomplete reads due to packet boundaries. - @param pBuffer receives the read data. - @param nSize the number of bytes to read. pBuffer must be large enough + @param[in] Socket The socket to read from. + @param[out] pBuffer receives the read data. + @param[out] nSize the number of bytes to read. pBuffer must be large enough to hold the n bytes! @return the number of read bytes. The number will only be smaller than n if an exceptional condition (e.g. connection closed) occurs. @@ -888,8 +898,9 @@ SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_readSocket( oslSocket Socket, void *pBuffer /** Writes n bytes from pBuffer to the stream. The method avoids incomplete writes due to packet boundaries. - @param pBuffer contains the data to be written. - @param nSize the number of bytes to write. + @param[out] Socket The socket to write to. + @param[in] pBuffer contains the data to be written. + @param[in] nSize the number of bytes to write. @return the number of written bytes. The number will only be smaller than nSize if an exceptional condition (e.g. connection closed) occurs. */ diff --git a/sal/inc/osl/socket_decl.hxx b/sal/inc/osl/socket_decl.hxx index 2b45b979cdaa..822450db8f1c 100644 --- a/sal/inc/osl/socket_decl.hxx +++ b/sal/inc/osl/socket_decl.hxx @@ -48,7 +48,6 @@ namespace osl /** The SocketAddr takes over the responsibility of the handle ( which means, that the handle gets destructed by the destructor of this reference) - @param nocopy use SAL_NO_COPY */ inline SocketAddr(const oslSocketAddr , __osl_socket_NoCopy nocopy ); @@ -116,6 +115,7 @@ namespace osl inline SocketAddr & SAL_CALL operator= (const SocketAddr& Addr); /** Assigns the socket addr without copyconstructing it. + @param Addr the socket address. @param nocopy use SAL_NO_COPY */ inline SocketAddr & SAL_CALL assign( oslSocketAddr Addr, __osl_socket_NoCopy nocopy ); @@ -180,6 +180,7 @@ namespace osl /** The instance takes over the handle's ownership without acquiring the handle, but releases it within the dtor. + @param socketHandle the handle @param noacquire use SAL_NO_ACQUIRE */ inline Socket( oslSocket socketHandle, __sal_NoAcquire noacquire ); @@ -498,6 +499,8 @@ namespace osl { public: /** Creates a socket. + @param Family the Family of the socket (Inet by default) + @param Protocol the Protocon of the socket (IP by default) @param Type For some protocols it might be desirable to use a different type than <code>osl_Socket_TypeStream</code> (like <code>osl_Socket_TypeSeqPacket</code>). @@ -579,6 +582,8 @@ namespace osl { public: /** Creates a socket that can connect to a (remote) host. + @param Family the Family of the socket (Inet by default) + @param Protocol the Protocon of the socket (IP by default) @param Type For some protocols it might be desirable to use a different type than sock_stream <code>osl_Socket_TypeSeqPacket</code> (like <code>osl_Socket_TypeSeqPacket</code>). @@ -649,6 +654,8 @@ namespace osl public: /** Creates a datagram socket. + @param Family the Family of the socket (Inet by default) + @param Protocol the Protocon of the socket (IP by default) @param Type is sock_dgram by default. */ inline DatagramSocket(oslAddrFamily Family= osl_Socket_FamilyInet, diff --git a/sal/inc/rtl/alloc.h b/sal/inc/rtl/alloc.h index de708ea3cecb..ef48d01719ee 100644 --- a/sal/inc/rtl/alloc.h +++ b/sal/inc/rtl/alloc.h @@ -31,7 +31,8 @@ extern "C" { /** Allocate memory. - @descr A call to this function will return NULL upon the requested + + A call to this function will return NULL upon the requested memory size being either zero or larger than currently allocatable. @param Bytes [in] memory size. @@ -43,9 +44,9 @@ SAL_DLLPUBLIC void * SAL_CALL rtl_allocateMemory ( /** Reallocate memory. - @descr A call to this function with parameter 'Ptr' being NULL - is equivalent to a rtl_allocateMemory() call. + A call to this function with parameter 'Ptr' being NULL + is equivalent to a rtl_allocateMemory() call. A call to this function with parameter 'Bytes' being 0 is equivalent to a rtl_freeMemory() call. @@ -72,7 +73,8 @@ SAL_DLLPUBLIC void SAL_CALL rtl_freeMemory ( /** Allocate and zero memory. - @descr A call to this function will return NULL upon the requested + + A call to this function will return NULL upon the requested memory size being either zero or larger than currently allocatable. @param Bytes [in] memory size. @@ -187,6 +189,7 @@ typedef struct rtl_cache_st rtl_cache_type; * @param destructor [in] object destructor callback function. * @param reclaim [in] reclaim callback function. * @param pUserArg [in] opaque argument passed to callback functions. + * @param pSource [in] opaque argument passed to callback functions. * @param nFlags [in] flags. * * @return pointer to rtl_cache_type, or NULL upon failure. diff --git a/sal/inc/rtl/bootstrap.h b/sal/inc/rtl/bootstrap.h index 76795ba8e566..67fed2d92660 100644 --- a/sal/inc/rtl/bootstrap.h +++ b/sal/inc/rtl/bootstrap.h @@ -106,6 +106,7 @@ extern "C" { is different than the executable file name. It must be given on command line. If it is given the executable ini-file is ignored. </li> + </ul> */ /** may be called by an application to set an ini-filename. @@ -115,7 +116,7 @@ extern "C" { If it is never called, the filename is based on the name of the executable, with the suffix ".ini" on Windows or "rc" on Unix. - @param pNameUri URL of the inifile with path but WITHOUT suffix (.ini or rc) + @param pFileUri URL of the inifile with path but WITHOUT suffix (.ini or rc) */ SAL_DLLPUBLIC void SAL_CALL rtl_bootstrap_setIniFileName( rtl_uString *pFileUri ) SAL_THROW_EXTERN_C(); @@ -186,7 +187,8 @@ SAL_DLLPUBLIC sal_Bool SAL_CALL rtl_bootstrap_get_from_handle( /** Returns the name of the inifile associated with this handle. - @param ppIniName contains after the call the name of the ini-filename. + @param handle [in] The handle got by <code>rtl_bootstrap_args_open()</code> + @param ppIniName [out] contains after the call the name of the ini-filename. */ SAL_DLLPUBLIC void SAL_CALL rtl_bootstrap_get_iniName_from_handle( rtlBootstrapHandle handle, rtl_uString ** ppIniName) diff --git a/sal/inc/rtl/cipher.h b/sal/inc/rtl/cipher.h index be90d12319f3..a116e57ba071 100644 --- a/sal/inc/rtl/cipher.h +++ b/sal/inc/rtl/cipher.h @@ -143,7 +143,7 @@ SAL_DLLPUBLIC rtlCipherError SAL_CALL rtl_cipher_init ( /** Encode a buffer under a given cipher algorithm. - @precond Initialized for a compatible cipher direction. + @pre Initialized for a compatible cipher direction. @see rtl_cipher_init() @param Cipher [in] cipher handle. @@ -161,7 +161,7 @@ SAL_DLLPUBLIC rtlCipherError SAL_CALL rtl_cipher_encode ( /** Decode a buffer under a given cipher algorithm. - @precond Initialized for a compatible cipher direction. + @pre Initialized for a compatible cipher direction. @see rtl_cipher_init() @param Cipher [in] cipher handle. @@ -193,7 +193,8 @@ SAL_DLLPUBLIC void SAL_CALL rtl_cipher_destroy ( * *======================================================================*/ /** Create a Blowfish cipher handle for the given mode. - @descr The Blowfish block cipher algorithm is specified in + + The Blowfish block cipher algorithm is specified in Bruce Schneier: Applied Cryptography, 2nd edition, ch. 14.3 @see rtl_cipher_create() @@ -248,7 +249,8 @@ SAL_DLLPUBLIC void SAL_CALL rtl_cipher_destroyBF ( * *======================================================================*/ /** Create a RC4 cipher handle for the given mode. - @descr The RC4 symmetric stream cipher algorithm is specified in + + The RC4 symmetric stream cipher algorithm is specified in Bruce Schneier: Applied Cryptography, 2nd edition, ch. 17.1 @see rtl_cipher_create() diff --git a/sal/inc/rtl/crc.h b/sal/inc/rtl/crc.h index aafd9cbba096..7fad87ef4f37 100644 --- a/sal/inc/rtl/crc.h +++ b/sal/inc/rtl/crc.h @@ -35,7 +35,8 @@ extern "C" { * *======================================================================*/ /** Evaluate CRC32 over given data. - @descr This function evaluates the CRC polynomial 0xEDB88320. + + This function evaluates the CRC polynomial 0xEDB88320. @param Crc [in] CRC32 over previous data or zero. @param Data [in] data buffer. diff --git a/sal/inc/rtl/digest.h b/sal/inc/rtl/digest.h index 7c01335db306..cc49838821f7 100644 --- a/sal/inc/rtl/digest.h +++ b/sal/inc/rtl/digest.h @@ -91,7 +91,7 @@ SAL_DLLPUBLIC rtlDigest SAL_CALL rtl_digest_create ( /** Destroy a digest handle. - @postcond Digest handle destroyed and invalid. + @post Digest handle destroyed and invalid. @param Digest [in] digest handle to be destroyed. @return None. */ @@ -145,8 +145,8 @@ SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_update ( /** Finalize a digest and retrieve the digest value. - @precond Digest value length must not be less than digest length. - @postcond Digest initialized to accept another update sequence. + @pre Digest value length must not be less than digest length. + @post Digest initialized to accept another update sequence. @see rtl_digest_queryLength() @see rtl_digest_update() @@ -169,8 +169,8 @@ SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_get ( #define RTL_DIGEST_LENGTH_MD2 16 /** Create a MD2 digest handle. - @descr The MD2 digest algorithm is specified in + The MD2 digest algorithm is specified in RFC 1319 (Informational) The MD2 Message-Digest Algorithm @@ -206,7 +206,8 @@ SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_getMD2 ( /** Evaluate a MD2 digest value from given data. - @descr This function performs an optimized call sequence on a + + This function performs an optimized call sequence on a single data buffer, avoiding digest creation and destruction. @see rtl_digest_updateMD2() @@ -232,8 +233,8 @@ SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_MD2 ( #define RTL_DIGEST_LENGTH_MD5 16 /** Create a MD5 digest handle. - @descr The MD5 digest algorithm is specified in + The MD5 digest algorithm is specified in RFC 1321 (Informational) The MD5 Message-Digest Algorithm @@ -269,10 +270,11 @@ SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_getMD5 ( /** Retrieve the raw (not finalized) MD5 digest value. - @descr This function is a non-standard replacement for + + This function is a non-standard replacement for rtl_digest_getMD5() and must be used with caution. - @postcond Digest initialized to accept another update sequence. + @post Digest initialized to accept another update sequence. @see rtl_digest_get() */ SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_rawMD5 ( @@ -282,7 +284,8 @@ SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_rawMD5 ( /** Evaluate a MD5 digest value from given data. - @descr This function performs an optimized call sequence on a + + This function performs an optimized call sequence on a single data buffer, avoiding digest creation and destruction. @see rtl_digest_updateMD5() @@ -308,8 +311,8 @@ SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_MD5 ( #define RTL_DIGEST_LENGTH_SHA 20 /** Create a SHA digest handle. - @descr The SHA digest algorithm is specified in + The SHA digest algorithm is specified in FIPS PUB 180 (Superseded by FIPS PUB 180-1) Secure Hash Standard @@ -345,7 +348,8 @@ SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_getSHA ( /** Evaluate a SHA digest value from given data. - @descr This function performs an optimized call sequence on a + + This function performs an optimized call sequence on a single data buffer, avoiding digest creation and destruction. @see rtl_digest_updateSHA() @@ -371,8 +375,8 @@ SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_SHA ( #define RTL_DIGEST_LENGTH_SHA1 20 /** Create a SHA1 digest handle. - @descr The SHA1 digest algorithm is specified in + The SHA1 digest algorithm is specified in FIPS PUB 180-1 (Supersedes FIPS PUB 180) Secure Hash Standard @@ -408,7 +412,8 @@ SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_getSHA1 ( /** Evaluate a SHA1 digest value from given data. - @descr This function performs an optimized call sequence on a + + This function performs an optimized call sequence on a single data buffer, avoiding digest creation and destruction. @see rtl_digest_updateSHA1() @@ -434,7 +439,8 @@ SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_SHA1 ( #define RTL_DIGEST_LENGTH_HMAC_MD5 RTL_DIGEST_LENGTH_MD5 /** Create a HMAC_MD5 digest handle. - @descr The HMAC_MD5 digest algorithm is specified in + + The HMAC_MD5 digest algorithm is specified in RFC 2104 (Informational) HMAC: Keyed-Hashing for Message Authentication @@ -486,7 +492,8 @@ SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_getHMAC_MD5 ( /** Evaluate a HMAC_MD5 digest value from given data. - @descr This function performs an optimized call sequence on a + + This function performs an optimized call sequence on a single data buffer, avoiding digest creation and destruction. @see rtl_digest_initHMAC_MD5() @@ -516,8 +523,8 @@ SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_HMAC_MD5 ( #define RTL_DIGEST_LENGTH_HMAC_SHA1 RTL_DIGEST_LENGTH_SHA1 /** Create a HMAC_SHA1 digest handle. - @descr The HMAC_SHA1 digest algorithm is specified in + The HMAC_SHA1 digest algorithm is specified in RFC 2104 (Informational) HMAC: Keyed-Hashing for Message Authentication RFC 2898 (Informational) @@ -570,7 +577,8 @@ SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_getHMAC_SHA1 ( /** Evaluate a HMAC_SHA1 digest value from given data. - @descr This function performs an optimized call sequence on a + + This function performs an optimized call sequence on a single data buffer, avoiding digest creation and destruction. @see rtl_digest_initHMAC_SHA1() @@ -598,8 +606,8 @@ SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_HMAC_SHA1 ( * *======================================================================*/ /** Password-Based Key Derivation Function. - @descr The PBKDF2 key derivation function is specified in + The PBKDF2 key derivation function is specified in RFC 2898 (Informational) PKCS #5: Password-Based Cryptography Specification Version 2.0 diff --git a/sal/inc/rtl/logfile.hxx b/sal/inc/rtl/logfile.hxx index 50083ca68626..5ee0739163e2 100644 --- a/sal/inc/rtl/logfile.hxx +++ b/sal/inc/rtl/logfile.hxx @@ -25,7 +25,7 @@ namespace rtl { /** -@descr The intended use for class Logfile is to write time stamp information +@brief The intended use for class Logfile is to write time stamp information for profiling purposes. Profiling output should only be generated for a special product version of OpenOffice @@ -93,7 +93,9 @@ namespace rtl { public: inline Logfile( const sal_Char *name ); - /** @descr Create a log file context where the message field consists of a project + /** Create a log file context + + Create a log file context where the message field consists of a project name, the author's shortcut, and the actual message. These three strings are written in a format that is understood by script that later parses the log file and that so can extract the three strings. diff --git a/sal/inc/rtl/strbuf.h b/sal/inc/rtl/strbuf.h index f966548e494f..05dd2de8c61c 100644 --- a/sal/inc/rtl/strbuf.h +++ b/sal/inc/rtl/strbuf.h @@ -79,12 +79,13 @@ SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_stringbuffer_newFromStringBuffer( If the <code>minimumCapacity</code> argument is nonpositive, this method takes no action and simply returns. - @param capacity in: old capicity, out: new capacity. - @param minimumCapacity the minimum desired capacity. + @param[in,out] This the String to operate on. + @param[in,out] capacity in: old capacity, out: new capacity. + @param[in] minimumCapacity the minimum desired capacity. */ SAL_DLLPUBLIC void SAL_CALL rtl_stringbuffer_ensureCapacity( - /*inout*/rtl_String ** This, - /*inout*/sal_Int32* capacity, + rtl_String ** This, + sal_Int32* capacity, sal_Int32 minimumCapacity); @@ -97,14 +98,15 @@ SAL_DLLPUBLIC void SAL_CALL rtl_stringbuffer_ensureCapacity( <code>offset</code>. The length of this string buffer increases by the length of the argument. - @param capacity the capacity of the string buffer - @param offset the offset. - @param str a character array. - @param len the number of characters to append. + @param[in,out] This the String to operate on. + @param[in,out] capacity the capacity of the string buffer + @param[in] offset the offset. + @param[in] str a character array. + @param[in] len the number of characters to append. */ SAL_DLLPUBLIC void SAL_CALL rtl_stringbuffer_insert( - /*inout*/rtl_String ** This, - /*inout*/sal_Int32 * capacity, + rtl_String ** This, + sal_Int32 * capacity, sal_Int32 offset, const sal_Char * str, sal_Int32 len); @@ -117,11 +119,12 @@ SAL_DLLPUBLIC void SAL_CALL rtl_stringbuffer_insert( start must be >= 0 && <= This->length - @param start The beginning index, inclusive - @param len The substring length + @param[in,out] This The String to operate on. + @param[in] start The beginning index, inclusive + @param[in] len The substring length */ SAL_DLLPUBLIC void SAL_CALL rtl_stringbuffer_remove( - /*inout*/rtl_String ** This, + rtl_String ** This, sal_Int32 start, sal_Int32 len ); diff --git a/sal/inc/rtl/strbuf.hxx b/sal/inc/rtl/strbuf.hxx index fe19227c41ba..b5d746eaa2d7 100644 --- a/sal/inc/rtl/strbuf.hxx +++ b/sal/inc/rtl/strbuf.hxx @@ -567,6 +567,7 @@ public: string are then appended to this string buffer. @param i an <code>sal_Int32</code>. + @param radix the radix @return this string buffer. */ OStringBuffer & append(sal_Int32 i, sal_Int16 radix = 10 ) @@ -584,6 +585,7 @@ public: string are then appended to this string buffer. @param l a <code>long</code>. + @param radix the radix @return this string buffer. */ OStringBuffer & append(sal_Int64 l, sal_Int16 radix = 10 ) @@ -780,6 +782,7 @@ public: @param offset the offset. @param i an <code>sal_Int32</code>. + @param radix the radix @return this string buffer. */ OStringBuffer & insert(sal_Int32 offset, sal_Int32 i, sal_Int16 radix = 10 ) @@ -803,6 +806,7 @@ public: @param offset the offset. @param l a <code>long</code>. + @param radix the radix @return this string buffer. */ OStringBuffer & insert(sal_Int32 offset, sal_Int64 l, sal_Int16 radix = 10 ) diff --git a/sal/inc/rtl/string.h b/sal/inc/rtl/string.h index 6fc834918045..a16d61e0bb99 100644 --- a/sal/inc/rtl/string.h +++ b/sal/inc/rtl/string.h @@ -855,11 +855,8 @@ SAL_DLLPUBLIC void SAL_CALL rtl_string_new( rtl_String ** newStr ) SAL_THROW_EXT alternatively pass ownership to an OUString with rtl::OUString(newStr, SAL_NO_ACQUIRE); - @param newStr - pointer to the new string. - - @param len - the number of characters. + @param[out] nLen the number of characters. + @return pointer to the new string. @since LibreOffice 4.1 */ @@ -936,9 +933,10 @@ SAL_DLLPUBLIC void SAL_CALL rtl_string_newFromStr_WithLength( rtl_String ** newS or beginIndex + count greater than the length of the string have undefined behaviour. - @param beginIndex the beginning index, inclusive. - @param count the number of characters. - @return the specified substring. + @param[out] newStr the specified substring. + @param[in] from the String to take the substring from. + @param[in] beginIndex the beginning index, inclusive. + @param[in] count the number of characters. @since LibreOffice 4.0 */ diff --git a/sal/inc/rtl/uri.h b/sal/inc/rtl/uri.h index 1e58e172d182..251af025ef82 100644 --- a/sal/inc/rtl/uri.h +++ b/sal/inc/rtl/uri.h @@ -33,13 +33,11 @@ extern "C" { /** Various predefined URI 'char classes.' - @descr A 'char class' defines which (ASCII) characters can be written 'as they are' in a part of a Uri, and which characters have to be written using escape sequences ('%' followed by two hex digits). Characters outside the ASCII range are always written using escape sequences. - @descr If there are other frequently used char classes, they can be added to this enumeration; the function rtl_getUriCharClass() has to be adapted then, too. @@ -48,58 +46,64 @@ typedef enum { /** The empty char class. - @descr All characters are written using escape sequences. */ rtl_UriCharClassNone, /** The RFC 2732 @<uric> char class. - @descr + @verbatim The 'valid' characters are !$&'()*+,-./:;=?@[]_~ plus digits and letters. + @endverbatim */ rtl_UriCharClassUric, /** The RFC 2396 @<uric_no_slash> char class. - @descr + @verbatim The 'valid' characters are !$&'()*+,-.:;=?@_~ plus digits and letters. + @endverbatim */ rtl_UriCharClassUricNoSlash, /** The RFC 2396 @<rel_segment> char class. - @descr + @verbatim The 'valid' characters are !$&'()*+,-.;=@_~ plus digits and letters. + @endverbatim */ rtl_UriCharClassRelSegment, /** The RFC 2396 @<reg_name> char class. - @descr + @verbatim The 'valid' characters are !$&'()*+,-.:;=@_~ plus digits and letters. + @endverbatim */ rtl_UriCharClassRegName, /** The RFC 2396 @<userinfo> char class. - @descr + @verbatim The 'valid' characters are !$&'()*+,-.:;=_~ plus digits and letters. + @endverbatim */ rtl_UriCharClassUserinfo, /** The RFC 2396 @<pchar> char class. - @descr + @verbatim The 'valid' characters are !$&'()*+,-.:=@_~ plus digits and letters. + @endverbatim */ rtl_UriCharClassPchar, /** The char class for the values of uno URL parameters. - @descr + @verbatim The 'valid' characters are !$&'()*+-./:?@_~ plus digits and letters. + @endverbatim */ rtl_UriCharClassUnoParamValue, @@ -115,7 +119,6 @@ typedef enum /** The special meaning of '%' is ignored (i.e., there are by definition no escape sequences in the input). - @descr This mechanism is useful to encode user input as part of a URI (e.g., the user-supplied password in an ftp URL---'%20abcde' is a valid password, so do not assume that the '%20' is an escaped space). @@ -126,7 +129,6 @@ typedef enum even if they represent characters that need not be escaped or if they do not even map to characters in the given charset. - @descr This mechanism is useful when passing on complete URIs more or less unmodified (e.g., within an HTTP proxy): missing escape sequences are added, but existing escape sequences are not touched (except that any @@ -138,7 +140,6 @@ typedef enum a first step; only those that represent characters that need to be escaped are kept intact. - @descr This mechanism is useful to properly encode complete URIs entered by the user: the URI is brought into a 'canonic form,' but care is taken not to damage (valid) escape sequences the (careful) user already @@ -176,7 +177,6 @@ typedef enum /** The text is returned in the form of an IURI (cf. draft-masinter-url-i18n-05.txt). - @descr All escape sequences representing ASCII characters (%00--%7F) are kept, all other escape sequences are interpreted as UTF-8 characters and translated to Unicode, if possible. @@ -185,7 +185,6 @@ typedef enum /** The text is decoded. - @descr All escape sequences representing characters from the given charset are decoded and translated to Unicode, if possible. */ @@ -204,7 +203,6 @@ rtl_UriDecodeMechanism; /** Map a predefined rtl_UriCharClass to a form usable by rtl_uriEncode(). - @descr The function rtl_uriEncode() expects an array of 128 booleans, and this function maps rtl_UriCharClass enumeration members to such arrays. diff --git a/sal/inc/rtl/ustrbuf.h b/sal/inc/rtl/ustrbuf.h index f52fac469f7d..7df10c18cc40 100644 --- a/sal/inc/rtl/ustrbuf.h +++ b/sal/inc/rtl/ustrbuf.h @@ -79,12 +79,13 @@ SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_uStringbuffer_newFromStringBuffer( If the <code>minimumCapacity</code> argument is nonpositive, this method takes no action and simply returns. - @param capacity in: old capicity, out: new capacity. - @param minimumCapacity the minimum desired capacity. + @param[in,out] This the String to operate on. + @param[in,out] capacity in: old capacity, out: new capacity. + @param[in] minimumCapacity the minimum desired capacity. */ SAL_DLLPUBLIC void SAL_CALL rtl_uStringbuffer_ensureCapacity( - /*inout*/rtl_uString ** This, - /*inout*/sal_Int32* capacity, + rtl_uString ** This, + sal_Int32* capacity, sal_Int32 minimumCapacity); /** @@ -165,11 +166,12 @@ SAL_DLLPUBLIC void SAL_CALL rtl_uStringbuffer_insert_ascii( start must be >= 0 && <= This->length - @param start The beginning index, inclusive - @param len The substring length + @param[in,out] This The String to operate on. + @param[in] start The beginning index, inclusive + @param[in] len The substring length */ SAL_DLLPUBLIC void SAL_CALL rtl_uStringbuffer_remove( - /*inout*/rtl_uString ** This, + rtl_uString ** This, sal_Int32 start, sal_Int32 len ); diff --git a/sal/inc/rtl/ustrbuf.hxx b/sal/inc/rtl/ustrbuf.hxx index 8e4ca1d80ba4..5743800fc2ef 100644 --- a/sal/inc/rtl/ustrbuf.hxx +++ b/sal/inc/rtl/ustrbuf.hxx @@ -667,6 +667,7 @@ public: string are then appended to this string buffer. @param i an <code>sal_Int32</code>. + @param radix the radix @return this string buffer. */ OUStringBuffer & append(sal_Int32 i, sal_Int16 radix = 10 ) @@ -684,6 +685,7 @@ public: string are then appended to this string buffer. @param l a <code>long</code>. + @param radix the radix @return this string buffer. */ OUStringBuffer & append(sal_Int64 l, sal_Int16 radix = 10 ) diff --git a/sal/inc/rtl/ustring.h b/sal/inc/rtl/ustring.h index ba19b83ee8cc..f6bf956c0c51 100644 --- a/sal/inc/rtl/ustring.h +++ b/sal/inc/rtl/ustring.h @@ -1207,11 +1207,8 @@ SAL_DLLPUBLIC void SAL_CALL rtl_uString_new( alternatively pass ownership to an OUString with rtl::OUString(newStr, SAL_NO_ACQUIRE); - @param newStr - pointer to the new string. - - @param len - the number of characters. + @param[in] nLen the number of characters. + @return pointer to the new string. @since LibreOffice 4.1 */ @@ -1292,8 +1289,10 @@ SAL_DLLPUBLIC void SAL_CALL rtl_uString_newFromStr_WithLength( or beginIndex + count greater than the length of the string have undefined behaviour. - @param beginIndex the beginning index, inclusive. - @param count the number of characters. + @param[out] newStr the specified substring. + @param[in] from the String to take the substring from. + @param[in] beginIndex the beginning index, inclusive. + @param[in] count the number of characters. @return the specified substring. @since LibreOffice 4.0 diff --git a/sal/inc/sal/log.hxx b/sal/inc/sal/log.hxx index 71e2d52ef7fe..340589e260e7 100644 --- a/sal/inc/sal/log.hxx +++ b/sal/inc/sal/log.hxx @@ -212,11 +212,15 @@ inline char const * unwrapStream(SAL_UNUSED_PARAMETER StreamIgnore const &) { For all the other macros, the given area argument must be non-null and must match the regular expression + @verbatim <area> ::= <segment>("."<segment>)* + @endverbatim with + @verbatim <segment> ::= [0-9a-z]+ + @endverbatim For a list of areas used see @ref sal_log_areas "SAL debug areas". Whenever you use a new log area, add it to the file sal/inc/sal/log-areas.dox . @@ -233,13 +237,17 @@ inline char const * unwrapStream(SAL_UNUSED_PARAMETER StreamIgnore const &) { macro calls actually generate log output. The environment variable SAL_LOG must either be unset or must match the regular expression + @verbatim <env> ::= <switch>* + @endverbatim with + @verbatim <switch> ::= <sense><level>("."<area>)? <sense> ::= "+"|"-" <level> ::= "INFO"|"WARN" + @endverbatim If the environment variable is unset, "+WARN" is used instead (which results in all warnings being output but no infos). If the given value does not |