Update comments in util to be doxygen compatible

This commit is contained in:
Michael Ford 2014-11-17 11:04:01 +08:00
parent 3d3ce7421e
commit c63a73d18a
8 changed files with 72 additions and 49 deletions

View File

@ -1,6 +1,6 @@
// Copyright (c) 2009-2010 Satoshi Nakamoto // Copyright (c) 2009-2010 Satoshi Nakamoto
// Copyright (c) 2009-2014 The Bitcoin developers // 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. // file COPYING or http://www.opensource.org/licenses/mit-license.php.
#if defined(HAVE_CONFIG_H) #if defined(HAVE_CONFIG_H)
@ -105,7 +105,7 @@ bool fLogTimestamps = false;
bool fLogIPs = false; bool fLogIPs = false;
volatile bool fReopenDebugLog = false; volatile bool fReopenDebugLog = false;
// Init OpenSSL library multithreading support /** Init OpenSSL library multithreading support */
static CCriticalSection** ppmutexOpenSSL; static CCriticalSection** ppmutexOpenSSL;
void locking_callback(int mode, int i, const char* file, int line) void locking_callback(int mode, int i, const char* file, int line)
{ {
@ -149,18 +149,22 @@ public:
} }
instance_of_cinit; instance_of_cinit;
// LogPrintf() has been broken a couple of times now /**
// by well-meaning people adding mutexes in the most straightforward way. * LogPrintf() has been broken a couple of times now
// It breaks because it may be called by global destructors during shutdown. * by well-meaning people adding mutexes in the most straightforward way.
// Since the order of destruction of static/global objects is undefined, * It breaks because it may be called by global destructors during shutdown.
// defining a mutex as a global object doesn't work (the mutex gets * Since the order of destruction of static/global objects is undefined,
// destroyed, and then some later destructor calls OutputDebugStringF, * defining a mutex as a global object doesn't work (the mutex gets
// maybe indirectly, and you get a core dump at shutdown trying to lock * destroyed, and then some later destructor calls OutputDebugStringF,
// the mutex). * maybe indirectly, and you get a core dump at shutdown trying to lock
* the mutex).
*/
static boost::once_flag debugPrintInitFlag = BOOST_ONCE_INIT; 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 FILE* fileout = NULL;
static boost::mutex* mutexDebugLog = NULL; static boost::mutex* mutexDebugLog = NULL;
@ -500,9 +504,11 @@ bool RenameOver(boost::filesystem::path src, boost::filesystem::path dest)
#endif /* WIN32 */ #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 * Ignores exceptions thrown by Boost's create_directory if the requested directory exists.
// write to the parent directory. * 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) bool TryCreateDirectory(const boost::filesystem::path& p)
{ {
try try
@ -542,8 +548,10 @@ bool TruncateFile(FILE *file, unsigned int length) {
#endif #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) { int RaiseFileDescriptorLimit(int nMinFD) {
#if defined(WIN32) #if defined(WIN32)
return 2048; return 2048;
@ -563,8 +571,10 @@ int RaiseFileDescriptorLimit(int nMinFD) {
#endif #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) { void AllocateFileRange(FILE *file, unsigned int offset, unsigned int length) {
#if defined(WIN32) #if defined(WIN32)
// Windows-specific version // Windows-specific version

View File

@ -1,6 +1,6 @@
// Copyright (c) 2009-2010 Satoshi Nakamoto // Copyright (c) 2009-2010 Satoshi Nakamoto
// Copyright (c) 2009-2014 The Bitcoin developers // 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. // file COPYING or http://www.opensource.org/licenses/mit-license.php.
/** /**
@ -40,25 +40,26 @@ extern volatile bool fReopenDebugLog;
void SetupEnvironment(); void SetupEnvironment();
/* Return true if log accepts specified category */ /** Return true if log accepts specified category */
bool LogAcceptCategory(const char* 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); int LogPrintStr(const std::string &str);
#define LogPrintf(...) LogPrint(NULL, __VA_ARGS__) #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). * of this macro-based construction (see tinyformat.h).
*/ */
#define MAKE_ERROR_AND_LOG_FUNC(n) \ #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<TINYFORMAT_ARGTYPES(n)> \ template<TINYFORMAT_ARGTYPES(n)> \
static inline int LogPrint(const char* category, const char* format, TINYFORMAT_VARARGS(n)) \ static inline int LogPrint(const char* category, const char* format, TINYFORMAT_VARARGS(n)) \
{ \ { \
if(!LogAcceptCategory(category)) return 0; \ if(!LogAcceptCategory(category)) return 0; \
return LogPrintStr(tfm::format(format, TINYFORMAT_PASSARGS(n))); \ return LogPrintStr(tfm::format(format, TINYFORMAT_PASSARGS(n))); \
} \ } \
/* Log error and return false */ \ /** Log error and return false */ \
template<TINYFORMAT_ARGTYPES(n)> \ template<TINYFORMAT_ARGTYPES(n)> \
static inline bool error(const char* format, TINYFORMAT_VARARGS(n)) \ 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) 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 * TINYFORMAT_FOREACH_ARGNUM
*/ */
static inline int LogPrint(const char* category, const char* format) 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 SetThreadPriority(int nPriority);
void RenameThread(const char* name); void RenameThread(const char* name);
// Standard wrapper for do-something-forever thread functions. /**
// "Forever" really means until the thread is interrupted. * Standard wrapper for do-something-forever thread functions.
// Use it like: * "Forever" really means until the thread is interrupted.
// new boost::thread(boost::bind(&LoopForever<void (*)()>, "dumpaddr", &DumpAddresses, 900000)); * Use it like:
// or maybe: * new boost::thread(boost::bind(&LoopForever<void (*)()>, "dumpaddr", &DumpAddresses, 900000));
// boost::function<void()> f = boost::bind(&FunctionWithArg, argument); * or maybe:
// threadGroup.create_thread(boost::bind(&LoopForever<boost::function<void()> >, "nothing", f, milliseconds)); * boost::function<void()> f = boost::bind(&FunctionWithArg, argument);
* threadGroup.create_thread(boost::bind(&LoopForever<boost::function<void()> >, "nothing", f, milliseconds));
*/
template <typename Callable> void LoopForever(const char* name, Callable func, int64_t msecs) template <typename Callable> void LoopForever(const char* name, Callable func, int64_t msecs)
{ {
std::string s = strprintf("bitcoin-%s", name); std::string s = strprintf("bitcoin-%s", name);
@ -196,7 +200,10 @@ template <typename Callable> void LoopForever(const char* name, Callable func,
throw; throw;
} }
} }
// .. and a wrapper that just calls func once
/**
* .. and a wrapper that just calls func once
*/
template <typename Callable> void TraceThread(const char* name, Callable func) template <typename Callable> void TraceThread(const char* name, Callable func)
{ {
std::string s = strprintf("bitcoin-%s", name); std::string s = strprintf("bitcoin-%s", name);

View File

@ -1,6 +1,6 @@
// Copyright (c) 2009-2010 Satoshi Nakamoto // Copyright (c) 2009-2010 Satoshi Nakamoto
// Copyright (c) 2009-2014 The Bitcoin developers // 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. // file COPYING or http://www.opensource.org/licenses/mit-license.php.
#include "utilmoneystr.h" #include "utilmoneystr.h"

View File

@ -1,6 +1,6 @@
// Copyright (c) 2009-2010 Satoshi Nakamoto // Copyright (c) 2009-2010 Satoshi Nakamoto
// Copyright (c) 2009-2014 The Bitcoin developers // 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. // file COPYING or http://www.opensource.org/licenses/mit-license.php.
/** /**

View File

@ -1,6 +1,6 @@
// Copyright (c) 2009-2010 Satoshi Nakamoto // Copyright (c) 2009-2010 Satoshi Nakamoto
// Copyright (c) 2009-2014 The Bitcoin developers // 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. // file COPYING or http://www.opensource.org/licenses/mit-license.php.
#include "utilstrencodings.h" #include "utilstrencodings.h"
@ -14,8 +14,10 @@
using namespace std; 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 .,;_/:?@()"); static string safeChars("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ01234567890 .,;_/:?@()");
string SanitizeString(const string& str) string SanitizeString(const string& str)
{ {

View File

@ -1,6 +1,6 @@
// Copyright (c) 2009-2010 Satoshi Nakamoto // Copyright (c) 2009-2010 Satoshi Nakamoto
// Copyright (c) 2009-2014 The Bitcoin developers // 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. // file COPYING or http://www.opensource.org/licenses/mit-license.php.
/** /**
@ -19,7 +19,7 @@
#define UEND(a) ((unsigned char*)&((&(a))[1])) #define UEND(a) ((unsigned char*)&((&(a))[1]))
#define ARRAYLEN(array) (sizeof(array)/sizeof((array)[0])) #define ARRAYLEN(array) (sizeof(array)/sizeof((array)[0]))
// This is needed because the foreach macro can't get over the comma in pair<t1, t2> /** This is needed because the foreach macro can't get over the comma in pair<t1, t2> */
#define PAIRTYPE(t1, t2) std::pair<t1, t2> #define PAIRTYPE(t1, t2) std::pair<t1, t2>
std::string SanitizeString(const std::string& str); 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. * Convert string to signed 32-bit integer with strict parse error feedback.
* @returns true if the entire string could be parsed as valid integer, * @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); 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); 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. * indentation to any added line.
*/ */
std::string FormatParagraph(const std::string in, size_t width=79, size_t indent=0); std::string FormatParagraph(const std::string in, size_t width=79, size_t indent=0);

View File

@ -1,6 +1,6 @@
// Copyright (c) 2009-2010 Satoshi Nakamoto // Copyright (c) 2009-2010 Satoshi Nakamoto
// Copyright (c) 2009-2014 The Bitcoin developers // 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. // file COPYING or http://www.opensource.org/licenses/mit-license.php.
#if defined(HAVE_CONFIG_H) #if defined(HAVE_CONFIG_H)
@ -14,7 +14,7 @@
using namespace std; using namespace std;
static int64_t nMockTime = 0; // For unit testing static int64_t nMockTime = 0; //! For unit testing
int64_t GetTime() int64_t GetTime()
{ {
@ -42,9 +42,12 @@ int64_t GetTimeMicros()
void MilliSleep(int64_t n) 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) #if defined(HAVE_WORKING_BOOST_SLEEP_FOR)
boost::this_thread::sleep_for(boost::chrono::milliseconds(n)); boost::this_thread::sleep_for(boost::chrono::milliseconds(n));
#elif defined(HAVE_WORKING_BOOST_SLEEP) #elif defined(HAVE_WORKING_BOOST_SLEEP)

View File

@ -1,6 +1,6 @@
// Copyright (c) 2009-2010 Satoshi Nakamoto // Copyright (c) 2009-2010 Satoshi Nakamoto
// Copyright (c) 2009-2014 The Bitcoin developers // 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. // file COPYING or http://www.opensource.org/licenses/mit-license.php.
#ifndef BITCOIN_UTILTIME_H #ifndef BITCOIN_UTILTIME_H