Doxygen #7196

pull awelch83 wants to merge 1 commits into bitcoin:master from awelch83:doxygen-a changing 12 files +264 −254

awelch83 commented at 11:31 PM on December 9, 2015: none

I made changes to *.cpp files beginning with the letter 'A'. I updated comments, where necessary, to Doxygen standards. This is my first contribution, so I only wanted to touch a few files. If this is accepted, I'll know that what I did here was correct, and will do the same with other files.
I made changes to *.cpp files beginning with the letter 'A'. I updated comments, where necessary, to Doxygen standards. 1dfe4a0bbd
jonasschnelli added the label Docs and Output on Dec 10, 2015
jonasschnelli commented at 7:41 AM on December 10, 2015: contributor

@fanquake: can you have a look at this? IIRC, you are a doxygen guy?
laanwj commented at 10:47 AM on December 10, 2015: member

What is the result of this in the rendered doxygen? I don't like changing every single comment in the source code. Would be good to focus on documentation bottlenecks: definitions of global variables, types, functions and methods.
MarcoFalke commented at 12:42 PM on December 10, 2015: member

Please also include the diff in the rendered output of doxygen. Only changes to comments where you can influence the output meaningful are preferred.
jamesob commented at 4:35 PM on December 10, 2015: member

NACK. I doubt we want all these comments in the rendered doxygen output; most of these are useless if read anywhere but the source. Per the developer notes, we only want to doxygen-document functions, methods, and fields.

in src/addrman.cpp:None in 1dfe4a0bbd

   0 | @@ -1,6 +1,6 @@
   1 | -// Copyright (c) 2012 Pieter Wuille
   2 | -// Distributed under the MIT software license, see the accompanying
   3 | -// file COPYING or http://www.opensource.org/licenses/mit-license.php.
   4 | +/// Copyright (c) 2012 Pieter Wuille
   5 | +/// Distributed under the MIT software license, see the accompanying
   6 | +/// file COPYING or http://www.opensource.org/licenses/mit-license.php.

fanquake commented at 2:54 AM on December 11, 2015:

We don't want any of these comments included in Doxygen, as they don't add value to the dev documentation.

in src/addrman.cpp:None in 1dfe4a0bbd

  30 | @@ -31,19 +31,24 @@ int CAddrInfo::GetBucketPosition(const uint256 &nKey, bool fNew, int nBucket) co
  31 |  
  32 |  bool CAddrInfo::IsTerrible(int64_t nNow) const
  33 |  {
  34 | -    if (nLastTry && nLastTry >= nNow - 60) // never remove things tried in the last minute
  35 | +    /// never remove things tried in the last minute

fanquake commented at 3:02 AM on December 11, 2015:

As pointed out, we also don't want these comments included, as they make the most sense in the context of the code. I'll add some screenshots of what they look like in Doxygen to this thread.

fanquake commented at 3:08 AM on December 11, 2015: member

This is how the changed comments in Addrman appear.
laanwj commented at 8:23 AM on December 11, 2015: member

Ok, closing this. Blanketly making function-internal comments visible in doxygen can be confusing, and generates a way-too-large diff.
laanwj closed this on Dec 11, 2015
DrahtBot locked this on Sep 8, 2021

Contributors

Labels