Addrman doxygenification #5131

pull fanquake wants to merge 2 commits into bitcoin:master from fanquake:addrman_doxygen changing 3 files +130 −119

fanquake commented at 7:01 AM on October 24, 2014: member

First look at changing comments to be doxygen compatible. Started with addrman.cpp/.h because they don't see many changes, and have a decent amount of comments/doc thoughout. This pull includes minor typo fixes and updating the license in both files; as well as a commit that adds doc/doxygen to .gitignore @laanwj What would you prefer be done with the larger doc blocks, i.e here.
Add doc/doxygen to .gitignore c772f4cb04
in src/addrman.cpp:None in 9a12334625 outdated
```
  38 | @@ -39,19 +39,19 @@ int CAddrInfo::GetNewBucket(const std::vector<unsigned char>& nKey, const CNetAd
  39 |  
  40 |  bool CAddrInfo::IsTerrible(int64_t nNow) const
  41 |  {
  42 | -    if (nLastTry && nLastTry >= nNow - 60) // never remove things tried the last minute
  43 | +    if (nLastTry && nLastTry >= nNow - 60) //! never remove things tried in the last minute
```
laanwj commented at 7:13 AM on October 24, 2014:

Any reason for changing comments within functions? Does doxygen ever show them? //! is meant for descriptions of variables and properties AFAIK.

fanquake commented at 7:16 AM on October 24, 2014:

Comments within functions are shown by doxygen. Maybe /// would be better suited here?

laanwj commented at 7:20 AM on October 24, 2014:

IMO it's better to just touch the API documenting comments for now, not those inside functions. (so those documenting the behaviour of functions, methods, classes, properties, etc...). I don't like to change every single comment in the program and require a specific comment style in functions.

fanquake commented at 7:52 AM on October 24, 2014:

Understood. Have pushed some changes.
laanwj commented at 7:16 AM on October 24, 2014: member
For larger comment blocks I generally use JavaDoc style syntax, ie
```
/**
 * ... text ...
 */
```
I'd suggest to take a look at the doxygen documentation, especially http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html on how to handle different cases.
fanquake force-pushed on Oct 24, 2014
Update comments in addrman to be doxygen compatible
Also correct the file license
24f5c94015
fanquake force-pushed on Oct 24, 2014
laanwj commented at 9:13 AM on October 24, 2014: member

Looks good to me now (tested w/ doxygen). ACK.
sipa commented at 5:11 PM on October 24, 2014: member

utACK
laanwj merged this on Oct 25, 2014
laanwj closed this on Oct 25, 2014
laanwj referenced this in commit b847e0139e on Oct 25, 2014
fanquake deleted the branch on May 12, 2016
DrahtBot locked this on Sep 8, 2021

Contributors

fanquake

laanwj

sipa