From c63a73d18aa60207790f24b9a910fd45eb3afaa3 Mon Sep 17 00:00:00 2001 From: Michael Ford Date: Mon, 17 Nov 2014 11:04:01 +0800 Subject: [PATCH] Update comments in util to be doxygen compatible --- src/util.cpp | 48 ++++++++++++++++++++++++---------------- src/util.h | 37 ++++++++++++++++++------------- src/utilmoneystr.cpp | 2 +- src/utilmoneystr.h | 2 +- src/utilstrencodings.cpp | 8 ++++--- src/utilstrencodings.h | 9 ++++---- src/utiltime.cpp | 13 ++++++----- src/utiltime.h | 2 +- 8 files changed, 72 insertions(+), 49 deletions(-) diff --git a/src/util.cpp b/src/util.cpp index 0f5c0363523..0cdf4e614d8 100644 --- a/src/util.cpp +++ b/src/util.cpp @@ -1,6 +1,6 @@ // Copyright (c) 2009-2010 Satoshi Nakamoto // Copyright (c) 2009-2014 The Bitcoin developers -// Distributed under the MIT/X11 software license, see the accompanying +// Distributed under the MIT software license, see the accompanying // file COPYING or http://www.opensource.org/licenses/mit-license.php. #if defined(HAVE_CONFIG_H) @@ -105,7 +105,7 @@ bool fLogTimestamps = false; bool fLogIPs = false; volatile bool fReopenDebugLog = false; -// Init OpenSSL library multithreading support +/** Init OpenSSL library multithreading support */ static CCriticalSection** ppmutexOpenSSL; void locking_callback(int mode, int i, const char* file, int line) { @@ -149,18 +149,22 @@ public: } instance_of_cinit; -// LogPrintf() has been broken a couple of times now -// by well-meaning people adding mutexes in the most straightforward way. -// It breaks because it may be called by global destructors during shutdown. -// Since the order of destruction of static/global objects is undefined, -// defining a mutex as a global object doesn't work (the mutex gets -// destroyed, and then some later destructor calls OutputDebugStringF, -// maybe indirectly, and you get a core dump at shutdown trying to lock -// the mutex). +/** + * LogPrintf() has been broken a couple of times now + * by well-meaning people adding mutexes in the most straightforward way. + * It breaks because it may be called by global destructors during shutdown. + * Since the order of destruction of static/global objects is undefined, + * defining a mutex as a global object doesn't work (the mutex gets + * destroyed, and then some later destructor calls OutputDebugStringF, + * maybe indirectly, and you get a core dump at shutdown trying to lock + * the mutex). + */ static boost::once_flag debugPrintInitFlag = BOOST_ONCE_INIT; -// We use boost::call_once() to make sure these are initialized -// in a thread-safe manner the first time called: +/** + * We use boost::call_once() to make sure these are initialized + * in a thread-safe manner the first time called: + */ static FILE* fileout = NULL; static boost::mutex* mutexDebugLog = NULL; @@ -500,9 +504,11 @@ bool RenameOver(boost::filesystem::path src, boost::filesystem::path dest) #endif /* WIN32 */ } -// Ignores exceptions thrown by Boost's create_directory if the requested directory exists. -// Specifically handles case where path p exists, but it wasn't possible for the user to -// write to the parent directory. +/** + * Ignores exceptions thrown by Boost's create_directory if the requested directory exists. + * Specifically handles case where path p exists, but it wasn't possible for the user to + * write to the parent directory. + */ bool TryCreateDirectory(const boost::filesystem::path& p) { try @@ -542,8 +548,10 @@ bool TruncateFile(FILE *file, unsigned int length) { #endif } -// this function tries to raise the file descriptor limit to the requested number. -// It returns the actual file descriptor limit (which may be more or less than nMinFD) +/** + * this function tries to raise the file descriptor limit to the requested number. + * It returns the actual file descriptor limit (which may be more or less than nMinFD) + */ int RaiseFileDescriptorLimit(int nMinFD) { #if defined(WIN32) return 2048; @@ -563,8 +571,10 @@ int RaiseFileDescriptorLimit(int nMinFD) { #endif } -// this function tries to make a particular range of a file allocated (corresponding to disk space) -// it is advisory, and the range specified in the arguments will never contain live data +/** + * this function tries to make a particular range of a file allocated (corresponding to disk space) + * it is advisory, and the range specified in the arguments will never contain live data + */ void AllocateFileRange(FILE *file, unsigned int offset, unsigned int length) { #if defined(WIN32) // Windows-specific version diff --git a/src/util.h b/src/util.h index 4b2415278ba..a4aaf29f914 100644 --- a/src/util.h +++ b/src/util.h @@ -1,6 +1,6 @@ // Copyright (c) 2009-2010 Satoshi Nakamoto // Copyright (c) 2009-2014 The Bitcoin developers -// Distributed under the MIT/X11 software license, see the accompanying +// Distributed under the MIT software license, see the accompanying // file COPYING or http://www.opensource.org/licenses/mit-license.php. /** @@ -40,25 +40,26 @@ extern volatile bool fReopenDebugLog; void SetupEnvironment(); -/* Return true if log accepts specified category */ +/** Return true if log accepts specified category */ bool LogAcceptCategory(const char* category); -/* Send a string to the log output */ +/** Send a string to the log output */ int LogPrintStr(const std::string &str); #define LogPrintf(...) LogPrint(NULL, __VA_ARGS__) -/* When we switch to C++11, this can be switched to variadic templates instead +/** + * When we switch to C++11, this can be switched to variadic templates instead * of this macro-based construction (see tinyformat.h). */ #define MAKE_ERROR_AND_LOG_FUNC(n) \ - /* Print to debug.log if -debug=category switch is given OR category is NULL. */ \ + /** Print to debug.log if -debug=category switch is given OR category is NULL. */ \ template \ static inline int LogPrint(const char* category, const char* format, TINYFORMAT_VARARGS(n)) \ { \ if(!LogAcceptCategory(category)) return 0; \ return LogPrintStr(tfm::format(format, TINYFORMAT_PASSARGS(n))); \ } \ - /* Log error and return false */ \ + /** Log error and return false */ \ template \ static inline bool error(const char* format, TINYFORMAT_VARARGS(n)) \ { \ @@ -68,7 +69,8 @@ int LogPrintStr(const std::string &str); TINYFORMAT_FOREACH_ARGNUM(MAKE_ERROR_AND_LOG_FUNC) -/* Zero-arg versions of logging and error, these are not covered by +/** + * Zero-arg versions of logging and error, these are not covered by * TINYFORMAT_FOREACH_ARGNUM */ static inline int LogPrint(const char* category, const char* format) @@ -162,13 +164,15 @@ bool SoftSetBoolArg(const std::string& strArg, bool fValue); void SetThreadPriority(int nPriority); void RenameThread(const char* name); -// Standard wrapper for do-something-forever thread functions. -// "Forever" really means until the thread is interrupted. -// Use it like: -// new boost::thread(boost::bind(&LoopForever, "dumpaddr", &DumpAddresses, 900000)); -// or maybe: -// boost::function f = boost::bind(&FunctionWithArg, argument); -// threadGroup.create_thread(boost::bind(&LoopForever >, "nothing", f, milliseconds)); +/** + * Standard wrapper for do-something-forever thread functions. + * "Forever" really means until the thread is interrupted. + * Use it like: + * new boost::thread(boost::bind(&LoopForever, "dumpaddr", &DumpAddresses, 900000)); + * or maybe: + * boost::function f = boost::bind(&FunctionWithArg, argument); + * threadGroup.create_thread(boost::bind(&LoopForever >, "nothing", f, milliseconds)); + */ template void LoopForever(const char* name, Callable func, int64_t msecs) { std::string s = strprintf("bitcoin-%s", name); @@ -196,7 +200,10 @@ template void LoopForever(const char* name, Callable func, throw; } } -// .. and a wrapper that just calls func once + +/** + * .. and a wrapper that just calls func once + */ template void TraceThread(const char* name, Callable func) { std::string s = strprintf("bitcoin-%s", name); diff --git a/src/utilmoneystr.cpp b/src/utilmoneystr.cpp index 267a5b845c6..085adae85e9 100644 --- a/src/utilmoneystr.cpp +++ b/src/utilmoneystr.cpp @@ -1,6 +1,6 @@ // Copyright (c) 2009-2010 Satoshi Nakamoto // Copyright (c) 2009-2014 The Bitcoin developers -// Distributed under the MIT/X11 software license, see the accompanying +// Distributed under the MIT software license, see the accompanying // file COPYING or http://www.opensource.org/licenses/mit-license.php. #include "utilmoneystr.h" diff --git a/src/utilmoneystr.h b/src/utilmoneystr.h index 65415afd3f3..6a153db5fa7 100644 --- a/src/utilmoneystr.h +++ b/src/utilmoneystr.h @@ -1,6 +1,6 @@ // Copyright (c) 2009-2010 Satoshi Nakamoto // Copyright (c) 2009-2014 The Bitcoin developers -// Distributed under the MIT/X11 software license, see the accompanying +// Distributed under the MIT software license, see the accompanying // file COPYING or http://www.opensource.org/licenses/mit-license.php. /** diff --git a/src/utilstrencodings.cpp b/src/utilstrencodings.cpp index 15094e59991..a961b3c5cdc 100644 --- a/src/utilstrencodings.cpp +++ b/src/utilstrencodings.cpp @@ -1,6 +1,6 @@ // Copyright (c) 2009-2010 Satoshi Nakamoto // Copyright (c) 2009-2014 The Bitcoin developers -// Distributed under the MIT/X11 software license, see the accompanying +// Distributed under the MIT software license, see the accompanying // file COPYING or http://www.opensource.org/licenses/mit-license.php. #include "utilstrencodings.h" @@ -14,8 +14,10 @@ using namespace std; -// safeChars chosen to allow simple messages/URLs/email addresses, but avoid anything -// even possibly remotely dangerous like & or > +/** + * safeChars chosen to allow simple messages/URLs/email addresses, but avoid anything + * even possibly remotely dangerous like & or > + */ static string safeChars("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ01234567890 .,;_/:?@()"); string SanitizeString(const string& str) { diff --git a/src/utilstrencodings.h b/src/utilstrencodings.h index 0b8c1a17818..0c0171b8944 100644 --- a/src/utilstrencodings.h +++ b/src/utilstrencodings.h @@ -1,6 +1,6 @@ // Copyright (c) 2009-2010 Satoshi Nakamoto // Copyright (c) 2009-2014 The Bitcoin developers -// Distributed under the MIT/X11 software license, see the accompanying +// Distributed under the MIT software license, see the accompanying // file COPYING or http://www.opensource.org/licenses/mit-license.php. /** @@ -19,7 +19,7 @@ #define UEND(a) ((unsigned char*)&((&(a))[1])) #define ARRAYLEN(array) (sizeof(array)/sizeof((array)[0])) -// This is needed because the foreach macro can't get over the comma in pair +/** This is needed because the foreach macro can't get over the comma in pair */ #define PAIRTYPE(t1, t2) std::pair std::string SanitizeString(const std::string& str); @@ -45,7 +45,7 @@ int atoi(const std::string& str); /** * Convert string to signed 32-bit integer with strict parse error feedback. * @returns true if the entire string could be parsed as valid integer, - * false if not the entire string could be parsed or when overflow or underflow occured. + * false if not the entire string could be parsed or when overflow or underflow occurred. */ bool ParseInt32(const std::string& str, int32_t *out); @@ -74,7 +74,8 @@ inline std::string HexStr(const T& vch, bool fSpaces=false) return HexStr(vch.begin(), vch.end(), fSpaces); } -/** Format a paragraph of text to a fixed width, adding spaces for +/** + * Format a paragraph of text to a fixed width, adding spaces for * indentation to any added line. */ std::string FormatParagraph(const std::string in, size_t width=79, size_t indent=0); diff --git a/src/utiltime.cpp b/src/utiltime.cpp index 78f0342cbab..9c137e8aa0a 100644 --- a/src/utiltime.cpp +++ b/src/utiltime.cpp @@ -1,6 +1,6 @@ // Copyright (c) 2009-2010 Satoshi Nakamoto // Copyright (c) 2009-2014 The Bitcoin developers -// Distributed under the MIT/X11 software license, see the accompanying +// Distributed under the MIT software license, see the accompanying // file COPYING or http://www.opensource.org/licenses/mit-license.php. #if defined(HAVE_CONFIG_H) @@ -14,7 +14,7 @@ using namespace std; -static int64_t nMockTime = 0; // For unit testing +static int64_t nMockTime = 0; //! For unit testing int64_t GetTime() { @@ -42,9 +42,12 @@ int64_t GetTimeMicros() void MilliSleep(int64_t n) { -// Boost's sleep_for was uninterruptable when backed by nanosleep from 1.50 -// until fixed in 1.52. Use the deprecated sleep method for the broken case. -// See: https://svn.boost.org/trac/boost/ticket/7238 + +/** + * Boost's sleep_for was uninterruptable when backed by nanosleep from 1.50 + * until fixed in 1.52. Use the deprecated sleep method for the broken case. + * See: https://svn.boost.org/trac/boost/ticket/7238 + */ #if defined(HAVE_WORKING_BOOST_SLEEP_FOR) boost::this_thread::sleep_for(boost::chrono::milliseconds(n)); #elif defined(HAVE_WORKING_BOOST_SLEEP) diff --git a/src/utiltime.h b/src/utiltime.h index 6f82e5a836f..9d7d42fe473 100644 --- a/src/utiltime.h +++ b/src/utiltime.h @@ -1,6 +1,6 @@ // Copyright (c) 2009-2010 Satoshi Nakamoto // Copyright (c) 2009-2014 The Bitcoin developers -// Distributed under the MIT/X11 software license, see the accompanying +// Distributed under the MIT software license, see the accompanying // file COPYING or http://www.opensource.org/licenses/mit-license.php. #ifndef BITCOIN_UTILTIME_H