Merge #15254: Trivial: fixup a few doxygen comments

70e7cee96028889ab709fa3c479225e584fcb77f Trivial: Doxygenize existing CBufferedFile and VectorReader comments (Ben Woosley)
9431e1b91598fc255234ede10c22208ad18685cd Trivial: fixup a few doxygen comments (Ben Woosley)

Pull request description:

  These were not declared properly, so their results are not properly
  processed. E.g.:
  https://dev.visucore.com/bitcoin/doxygen/rpcdump_8cpp.html#a994c8748aaa60fbb78009ff8a0638dea
  https://dev.visucore.com/bitcoin/doxygen/coins_8cpp.html#aa03af24ef3570144b045f4fca7a0d603
  https://dev.visucore.com/bitcoin/doxygen/wallet_2wallet_8cpp.html#a5c2a7725ff8796f03471f844ecded3d9

  > A third alternative is to use a block of at least two C++ comment lines, where each line starts with an additional slash or an exclamation mark.

  http://www.doxygen.nl/manual/docblocks.html

Tree-SHA512: c13fd48ac78f25e51b1281385747e8be4bd6e27e0a0f8704608aa5c66c16715c639f1cf27018b1bf05fc2eaed6c7b9be05a68365ffe1d88dd3f400d453b7bead

src/coins.h

@@ -309,17 +309,17 @@ private:
 };
 
 //! Utility function to add all of a transaction's outputs to a cache.
-// When check is false, this assumes that overwrites are only possible for coinbase transactions.
-// When check is true, the underlying view may be queried to determine whether an addition is
-// an overwrite.
+//! When check is false, this assumes that overwrites are only possible for coinbase transactions.
+//! When check is true, the underlying view may be queried to determine whether an addition is
+//! an overwrite.
 // TODO: pass in a boolean to limit these possible overwrites to known
 // (pre-BIP34) cases.
 void AddCoins(CCoinsViewCache& cache, const CTransaction& tx, int nHeight, bool check = false);
 
 //! Utility function to find any unspent output with a given txid.
-// This function can be quite expensive because in the event of a transaction
-// which is not found in the cache, it can cause up to MAX_OUTPUTS_PER_BLOCK
-// lookups to database, so it should be used with care.
+//! This function can be quite expensive because in the event of a transaction
+//! which is not found in the cache, it can cause up to MAX_OUTPUTS_PER_BLOCK
+//! lookups to database, so it should be used with care.
 const Coin& AccessByTxid(const CCoinsViewCache& cache, const uint256& txid);
 
 #endif // BITCOIN_COINS_H

src/net.h

@@ -438,17 +438,17 @@ public:
     void SetMaxOutboundTimeframe(uint64_t timeframe);
     uint64_t GetMaxOutboundTimeframe();
 
-    //!check if the outbound target is reached
-    // if param historicalBlockServingLimit is set true, the function will
-    // response true if the limit for serving historical blocks has been reached
+    //! check if the outbound target is reached
+    //! if param historicalBlockServingLimit is set true, the function will
+    //! response true if the limit for serving historical blocks has been reached
     bool OutboundTargetReached(bool historicalBlockServingLimit);
 
-    //!response the bytes left in the current max outbound cycle
-    // in case of no limit, it will always response 0
+    //! response the bytes left in the current max outbound cycle
+    //! in case of no limit, it will always response 0
     uint64_t GetOutboundTargetBytesLeft();
 
-    //!response the time in second left in the current max outbound cycle
-    // in case of no limit, it will always response 0
+    //! response the time in second left in the current max outbound cycle
+    //! in case of no limit, it will always response 0
     uint64_t GetMaxOutboundTimeLeftInCycle();
 
     uint64_t GetTotalBytesRecv();

src/streams.h

@@ -150,7 +150,7 @@ private:
 
 public:
 
-    /*
+    /**
      * @param[in]  type Serialization Type
      * @param[in]  version Serialization Version (including any flags)
      * @param[in]  data Referenced byte vector to overwrite/append
@@ -162,7 +162,7 @@ public:
         seek(pos);
     }
 
-    /*
+    /**
      * (other params same as above)
      * @param[in]  args  A list of items to deserialize starting at pos.
      */
@@ -732,15 +732,15 @@ private:
     const int nType;
     const int nVersion;
 
-    FILE *src;            // source file
-    uint64_t nSrcPos;     // how many bytes have been read from source
-    uint64_t nReadPos;    // how many bytes have been read from this
-    uint64_t nReadLimit;  // up to which position we're allowed to read
-    uint64_t nRewind;     // how many bytes we guarantee to rewind
-    std::vector<char> vchBuf; // the buffer
+    FILE *src;            //!< source file
+    uint64_t nSrcPos;     //!< how many bytes have been read from source
+    uint64_t nReadPos;    //!< how many bytes have been read from this
+    uint64_t nReadLimit;  //!< up to which position we're allowed to read
+    uint64_t nRewind;     //!< how many bytes we guarantee to rewind
+    std::vector<char> vchBuf; //!< the buffer
 
 protected:
-    // read data from the source to fill the buffer
+    //! read data from the source to fill the buffer
     bool Fill() {
         unsigned int pos = nSrcPos % vchBuf.size();
         unsigned int readNow = vchBuf.size() - pos;
@@ -786,12 +786,12 @@ public:
         }
     }
 
-    // check whether we're at the end of the source file
+    //! check whether we're at the end of the source file
     bool eof() const {
         return nReadPos == nSrcPos && feof(src);
     }
 
-    // read a number of bytes
+    //! read a number of bytes
     void read(char *pch, size_t nSize) {
         if (nSize + nReadPos > nReadLimit)
             throw std::ios_base::failure("Read attempted past buffer limit");
@@ -811,12 +811,12 @@ public:
         }
     }
 
-    // return the current reading position
+    //! return the current reading position
     uint64_t GetPos() const {
         return nReadPos;
     }
 
-    // rewind to a given reading position
+    //! rewind to a given reading position
     bool SetPos(uint64_t nPos) {
         size_t bufsize = vchBuf.size();
         if (nPos + bufsize < nSrcPos) {
@@ -845,8 +845,8 @@ public:
         return true;
     }
 
-    // prevent reading beyond a certain position
-    // no argument removes the limit
+    //! prevent reading beyond a certain position
+    //! no argument removes the limit
     bool SetLimit(uint64_t nPos = std::numeric_limits<uint64_t>::max()) {
         if (nPos < nReadPos)
             return false;
@@ -861,7 +861,7 @@ public:
         return (*this);
     }
 
-    // search for a given byte in the stream, and remain positioned on it
+    //! search for a given byte in the stream, and remain positioned on it
     void FindByte(char ch) {
         while (true) {
             if (nReadPos == nSrcPos)

src/wallet/wallet.h

@@ -602,8 +602,8 @@ public:
     int64_t nTimeCreated;
     int64_t nTimeExpires;
     std::string strComment;
-    //! todo: add something to note what created it (user, getnewaddress, change)
-    //!   maybe should have a map<string, string> property map
+    // todo: add something to note what created it (user, getnewaddress, change)
+    //   maybe should have a map<string, string> property map
 
     explicit CWalletKey(int64_t nExpires=0);