Merge pull request #1774 from ellert/doxygen-fixes

Address some warnings from Doxygen

src/Xrd/XrdLink.hh

@@ -153,7 +153,7 @@ static XrdLink *Find(int &curr, XrdLinkMatch *who=0);
 //-----------------------------------------------------------------------------
 //! Find the next client name matching certain attributes.
 //!
-//! @param  cur     Is an internal tracking value that allows repeated calls.
+//! @param  curr    Is an internal tracking value that allows repeated calls.
 //!                 It must be set to a value of 0 or less on the initial call
 //!                 and not touched therafter unless zero is returned.
 //! @param  bname   Pointer to a buffer where the name is to be returned.
@@ -306,7 +306,8 @@ int             Recv(char *buff, int blen, int timeout);
 //!
 //! @param  iov     pointer to the message vector.
 //! @param  iocnt   number of iov elements in the vector.
-//! @param  bytes   the sum of the sizes in the vector.
+//! @param  timeout milliseconds to wait for data. A negative value waits
+//!                 forever.
 //!
 //! @return >=0     number of bytes read.
 //!         < 0     an error occurred or when -ETIMEDOUT is returned, no data
@@ -336,9 +337,9 @@ int             RecvAll(char *buff, int blen, int timeout=-1);
 //------------------------------------------------------------------------------
 //! Register a host name with this IP address. This is not MT-safe!
 //!
-//! @param  hName    -> to a true host name which should be fully qualified.
-//!                     One of the IP addresses registered to this name must
-//!                     match the IP address associated with this object.
+//! @param  hName  pointer to a true host name which should be fully qualified.
+//!                One of the IP addresses registered to this name must
+//!                match the IP address associated with this object.
 //!
 //! @return True:    Specified name is now associated with this link.
 //!         False:   Nothing changed, registration could not be verified.
@@ -479,7 +480,7 @@ bool            setTLS(bool enable, XrdTlsContext *ctx=0);
 //-----------------------------------------------------------------------------
 //! Shutdown the link but otherwise keep it intact.
 //!
-//! @param  getlock if true, the operation is performed under a lock.
+//! @param  getLock if true, the operation is performed under a lock.
 //-----------------------------------------------------------------------------
 
 void            Shutdown(bool getLock);
@@ -555,9 +556,6 @@ bool            hasBridge() const {return isBridged;}
 //-----------------------------------------------------------------------------
 //! Determine if this link is using TLS.
 //!
-//! @param  vprot   if not nil, the TLS protocol version number if returned.
-//!                 If the link is not using TLS the version is a null string.
-//!
 //! @return true    this link is  using TLS.
 //! @return false   this link not using TLS.
 //-----------------------------------------------------------------------------

src/Xrd/XrdLinkCtl.hh

@@ -110,7 +110,7 @@ static XrdPollInfo *fd2PollInfo(int fd)
 //-----------------------------------------------------------------------------
 //! Find the next link matching certain attributes.
 //!
-//! @param  cur     Is an internal tracking value that allows repeated calls.
+//! @param  curr    Is an internal tracking value that allows repeated calls.
 //!                 It must be set to a value of 0 or less on the initial call
 //!                 and not touched therafter unless a null pointer is returned.
 //! @param  who     If the object use to check if teh link matches the wanted
@@ -128,7 +128,7 @@ static XrdLink  *Find(int &curr, XrdLinkMatch *who=0);
 //-----------------------------------------------------------------------------
 //! Find the next client name matching certain attributes.
 //!
-//! @param  cur     Is an internal tracking value that allows repeated calls.
+//! @param  curr    Is an internal tracking value that allows repeated calls.
 //!                 It must be set to a value of 0 or less on the initial call
 //!                 and not touched therafter unless zero is returned.
 //! @param  bname   Pointer to a buffer where the name is to be returned.
@@ -152,8 +152,8 @@ static void     idleScan();
 //-----------------------------------------------------------------------------
 //! Set kill constants.
 //!
-//! @param  wksec   Seconds to wait for kill to happed,
-//! @param  kwsec   The minimum number of seconds to wait after killing a
+//! @param  wkSec   Seconds to wait for kill to happed,
+//! @param  kwSec   The minimum number of seconds to wait after killing a
 //!                 connection for it to end.
 //-----------------------------------------------------------------------------
 
@@ -162,7 +162,7 @@ static void     setKWT(int wkSec, int kwSec);
 //-----------------------------------------------------------------------------
 //! Setup link processing.
 //!
-//! @param  maaxfds The maximum number of connections to handle.
+//! @param  maxfds  The maximum number of connections to handle.
 //! @param  idlewt  The time interval to check for idle connections.
 //!
 //! @return !0      Successful.

src/Xrd/XrdTcpMonPin.hh

@@ -37,7 +37,9 @@
     object exists in the environment. You get the g-stream object specific
     to this plugin by executing the following (assume envR is the environment):
 
+    @code {.cpp}
     XrdXrootdGStream *gS = (XrdXrootdGStream *)envR.GetPtr("TcpMon.gStream*");
+    @endcode
 */
 
 class XrdTcpMonPin

src/XrdApps/XrdClRecordPlugin/XrdClRecorder.hh

@@ -221,7 +221,7 @@ public:
 
   //----------------------------------------------------------------------------
   //! Create the output csv file
-  //! @param path : path for the file to be created
+  //! @param cfgpath : path for the file to be created
   //----------------------------------------------------------------------------
   inline static void SetOutput( const std::string &cfgpath )
   {

src/XrdCks/XrdCksLoader.hh

@@ -50,7 +50,7 @@ public:
 //! and md5 checksums are natively supported. Up to five more checksum
 //! algorithms can be loaded from shared libraries.
 //!
-//! @param  csNme    The name of the checksum algorithm (e.g. md5).
+//! @param  csName   The name of the checksum algorithm (e.g. md5).
 //! @param  csParms  Any parameters that might be needed by the checksum
 //!                  algorithm should it be loaded from a shared library.
 //! @param  eBuff    Optional pointer to a buffer to receive the reason for a

src/XrdCks/XrdCksWrapper.hh

@@ -233,7 +233,7 @@ int        Ver(  const char *Xfn, XrdCksData &Cks, XrdCksPCB *pcbP)
 //! Constructor
 //!
 //! @param  prevPI   Reference to the antecedent plugin.
-//! Wparam  errP     Pointer to error message object
+//! @param  errP     Pointer to error message object
 //------------------------------------------------------------------------------
 
            XrdCksWrapper(XrdCks &prevPI, XrdSysError *errP)

src/XrdCl/XrdClArg.hh

@@ -163,7 +163,7 @@ namespace XrdCl
           //--------------------------------------------------------------------
           //! Constructor
           //!
-          //! @param value : the future value to be hold by us
+          //! @param ftr : the future value to be hold by us
           //--------------------------------------------------------------------
           FutureValue( std::future<T> &&ftr ) : ftr( std::move( ftr ) )
           {
@@ -195,7 +195,7 @@ namespace XrdCl
           //--------------------------------------------------------------------
           //! Constructor
           //!
-          //! @param value : the forwarded value to be hold by us
+          //! @param fwd : the forwarded value to be hold by us
           //--------------------------------------------------------------------
           FwdValue( const Fwd<T> &fwd ) : fwd( fwd )
           {
@@ -305,7 +305,7 @@ namespace XrdCl
       //------------------------------------------------------------------------
       //! Constructor.
       //!
-      //! @param value : value of the argument
+      //! @param str : value of the argument
       //------------------------------------------------------------------------
       Arg( std::string str ) : ArgBase<std::string>( str )
       {
@@ -314,7 +314,7 @@ namespace XrdCl
       //------------------------------------------------------------------------
       //! Constructor.
       //!
-      //! @param val : value of the argument
+      //! @param cstr : value of the argument
       //------------------------------------------------------------------------
       Arg( const char *cstr ) : ArgBase<std::string>( cstr )
       {

src/XrdCl/XrdClAsyncHSWriter.hh

@@ -41,7 +41,6 @@ namespace XrdCl
       //------------------------------------------------------------------------
       //! Constructor
       //!
-      //! @param xrdTransport : the (xrootd) transport layer
       //! @param socket       : the socket with the message to be read out
       //! @param strmname     : stream name
       //------------------------------------------------------------------------

src/XrdCl/XrdClAsyncPageReader.hh

@@ -42,10 +42,7 @@ class AsyncPageReader
     //! Constructor
     //!
     //! @param chunks  : list of buffer for the data
-    //! @param socket  : the socket with the data
     //! @param digests : a vector that will be filled with crc32c digest data
-    //! @param dlen    : total size of data (including crc32 digests) in the
-    //!                  server response
     //--------------------------------------------------------------------------
     AsyncPageReader( ChunkList             &chunks,
                      std::vector<uint32_t> &digests ) :
@@ -100,7 +97,8 @@ class AsyncPageReader
     }
 
     //--------------------------------------------------------------------------
-    //! Readout date from the socket
+    //! Readout data from the socket
+    //! @param socket  : the socket with the data 
     //! @param btsread : number of user data read from the socket
     //! @return        : operation status
     //--------------------------------------------------------------------------

src/XrdCl/XrdClChannel.hh

@@ -83,16 +83,15 @@ namespace XrdCl
       //! pushed through the wire or when the timeout elapses
       //!
       //! @param msg     message to be sent
-      //! @apram stateful physical stream disconnection causes an error
+      //! @param handler handler to be notified about the status
+      //! @param stateful physical stream disconnection causes an error
       //! @param expires unix timestamp after which a failure is reported
       //!                to the listener
-      //! @param handler handler to be notified about the status
-      //! @param redirector virtual redirector to be used
       //! @return        success if the message was successfully inserted
       //!                into the send queues, failure otherwise
       //------------------------------------------------------------------------
       XRootDStatus Send( Message              *msg,
-                         MsgHandler   *handler,
+                         MsgHandler           *handler,
                          bool                  stateful,
                          time_t                expires );
 

src/XrdCl/XrdClFile.hh

@@ -218,8 +218,8 @@ namespace XrdCl
       //! @param offset    offset from the beginning of the file
       //! @param size    buffer size, at least 1 page big (4KB)
       //! @param buffer    a pointer to a buffer big enough to hold the data
-      //! @param bytesRead number of bytes actually read
       //! @param cksums    crc32c checksum for each read 4KB page
+      //! @param bytesRead number of bytes actually read
       //! @param timeout   timeout value, if 0 the environment default will be
       //!                  used
       //! @return          status of the operation
@@ -525,7 +525,6 @@ namespace XrdCl
       //! @param offset    offset from the beginning of the file
       //! @param iov       list of the buffers to
       //! @param iovcnt    number of buffers
-      //! @param handler   handler to be notified when the response arrives
       //! @param timeout   timeout value, if 0 then the environment default
       //!                  will be used
       //! @return          status of the operation
@@ -558,7 +557,7 @@ namespace XrdCl
       //! @param offset    offset from the beginning of the file
       //! @param iov       list of the buffers to be written
       //! @param iovcnt    number of buffers
-      //! @param handler   handler to be notified when the response arrives
+      //! @param bytesRead number of bytes actually read
       //! @param timeout   timeout value, if 0 then the environment default
       //!                  will be used
       //! @return          status of the operation

src/XrdCl/XrdClFileOperations.hh

@@ -154,7 +154,7 @@ namespace XrdCl
       //!
       //! @arg from : state from which the object is being converted
       //!
-      //! @param op : the object that is being converted
+      //! @param open : the object that is being converted
       //------------------------------------------------------------------------
       template<bool from>
       OpenImpl( OpenImpl<from> && open ) :
@@ -173,7 +173,7 @@ namespace XrdCl
       //! Overload of operator>> defined in ConcreteOperation, we're adding
       //! additional capabilities by using ExResp factory (@see ExResp).
       //!
-      //! @param func : function/functor/lambda
+      //! @param hdlr : function/functor/lambda
       //------------------------------------------------------------------------
       template<typename Hdlr>
       OpenImpl<true> operator>>( Hdlr &&hdlr )
@@ -195,8 +195,8 @@ namespace XrdCl
       //------------------------------------------------------------------------
       //! RunImpl operation (@see Operation)
       //!
-      //! @param timeout : pipeline timeout
-      //! @return        : status of the operation
+      //! @param pipelineTimeout : pipeline timeout
+      //! @return                : status of the operation
       //------------------------------------------------------------------------
       XRootDStatus RunImpl( PipelineHandler *handler, uint16_t pipelineTimeout )
       {

src/XrdCl/XrdClFileStateHandler.hh

@@ -331,7 +331,6 @@ namespace XrdCl
       //! @param offset  offset from the beginning of the file
       //! @param size    buffer size
       //! @param buffer  a pointer to a buffer holding data pages
-      //! @param cksums  the crc32c checksums for each 4KB page
       //! @param handler handler to be notified when the response arrives
       //! @param timeout timeout value, if 0 the environment default will be
       //!                used

src/XrdCl/XrdClLocalFileHandler.hh

@@ -179,8 +179,7 @@ namespace XrdCl
       //! Write scattered buffers in one operation - async
       //!
       //! @param offset    offset from the beginning of the file
-      //! @param iov       list of the buffers to be written
-      //! @param iovcnt    number of buffers
+      //! @param chunks    list of the chunks to be read
       //! @param handler   handler to be notified when the response arrives
       //! @param timeout   timeout value, if 0 then the environment default
       //!                  will be used
@@ -292,10 +291,9 @@ namespace XrdCl
                               uint16_t                   timeout = 0 );
 
       //------------------------------------------------------------------------
-      //! creates the directories specified in file_path
+      //! creates the directories specified in path
       //!
-      //! @param file_path specifies which directories are to be created
-      //! @param mode      same access modes as for the desired file operation
+      //! @param path      specifies which directories are to be created
       //! @return          status of the mkdir system call
       //------------------------------------------------------------------------
       static XRootDStatus MkdirPath( const std::string &path );

src/XrdCl/XrdClLog.hh

@@ -161,7 +161,7 @@ namespace XrdCl
       //! Always print the message
       //!
       //! @param level  log level
-      //! @param type   topic of the message
+      //! @param topic  topic of the message
       //! @param format format string - the same as in printf
       //! @param list   list of arguments
       //------------------------------------------------------------------------

src/XrdCl/XrdClMetalinkRedirector.hh

@@ -37,7 +37,6 @@ class MetalinkRedirector : public VirtualRedirector
     //----------------------------------------------------------------------------
     //! Constructor
     //! @param url         : URL to the metalink file
-    //! @param userHandler : the response handler provided by end user
     //----------------------------------------------------------------------------
     MetalinkRedirector( const std::string &url );
 
@@ -48,6 +47,7 @@ class MetalinkRedirector : public VirtualRedirector
 
     //----------------------------------------------------------------------------
     //! Initializes the object with the content of the metalink file
+    //! @param userHandler : the response handler provided by end user
     //----------------------------------------------------------------------------
     XRootDStatus Load( ResponseHandler *userHandler );
 

src/XrdCl/XrdClOperationHandlers.hh

@@ -620,8 +620,8 @@ namespace XrdCl
       //------------------------------------------------------------------------
       //!  A factory method, simply forwards the given handler
       //!
-      //! @param h : the ResponseHandler that should be wrapped
-      //! @return  : a ForwardingHandler instance
+      //! @param hdlr : the ResponseHandler that should be wrapped
+      //! @return     : a ForwardingHandler instance
       //------------------------------------------------------------------------
       inline static ResponseHandler* Create( ResponseHandler *hdlr )
       {
@@ -631,8 +631,8 @@ namespace XrdCl
       //------------------------------------------------------------------------
       //!  A factory method, simply forwards the given handler
       //!
-      //! @param h : the ResponseHandler that should be wrapped
-      //! @return  : a ForwardingHandler instance
+      //! @param hdlr : the ResponseHandler that should be wrapped
+      //! @return     : a ForwardingHandler instance
       //------------------------------------------------------------------------
       inline static ResponseHandler* Create( ResponseHandler &hdlr )
       {
@@ -687,7 +687,7 @@ namespace XrdCl
       //------------------------------------------------------------------------
       //! A factory method
       //!
-      //! @param func : the task that should be wrapped
+      //! @param task : the task that should be wrapped
       //! @return     : TaskWrapper instance
       //------------------------------------------------------------------------
       template<typename Return>
@@ -736,7 +736,7 @@ namespace XrdCl
       //------------------------------------------------------------------------
       //! A factory method
       //!
-      //! @param func : the task that should be wrapped
+      //! @param task : the task that should be wrapped
       //! @return     : TaskWrapper instance
       //------------------------------------------------------------------------
       template<typename Return>