doc: Add to Doxygen documentation guidelines #16948

pull ch4ot1c wants to merge 1 commits into bitcoin:master from ch4ot1c:doc/devnotes-doxygen changing 1 files +86 −52

ch4ot1c commented at 11:20 PM on September 23, 2019: contributor

Add some tips to developer-notes.md, gathered while doing #16947. Also suggests the simpler : notation for Javadoc arguments and adds @return and @param[out] example.
fanquake added the label Docs on Sep 23, 2019
ch4ot1c force-pushed on Sep 24, 2019

in doc/developer-notes.md:196 in b55a4a312e outdated

 190 | @@ -189,9 +191,18 @@ Not OK (used plenty in the current source, but not picked up):
 191 |  A full list of comment syntaxes picked up by Doxygen can be found at http://www.doxygen.nl/manual/docblocks.html,
 192 |  but the above styles are favored.
 193 |  
 194 | +Other recommendations:
 195 | +
 196 | +- Avoid redundant type and in/out information in function descriptions

laanwj commented at 9:21 AM on September 25, 2019:

Can you give an example for all of these? (like the cases above)

ch4ot1c commented at 6:41 AM on October 2, 2019:

Added some examples and simplified recommendations.

in doc/developer-notes.md:197 in b55a4a312e outdated

 190 | @@ -189,9 +191,18 @@ Not OK (used plenty in the current source, but not picked up):
 191 |  A full list of comment syntaxes picked up by Doxygen can be found at http://www.doxygen.nl/manual/docblocks.html,
 192 |  but the above styles are favored.
 193 |  
 194 | +Other recommendations:
 195 | +
 196 | +- Avoid redundant type and in/out information in function descriptions
 197 | +- Use backticks (&#96;&#96;) to refer to `argument`s in function descriptions

jonatack commented at 4:49 PM on September 26, 2019:

suggestion for readability: s/arguments/argument names/

in doc/developer-notes.md:200 in b55a4a312e outdated

 195 | +
 196 | +- Avoid redundant type and in/out information in function descriptions
 197 | +- Use backticks (&#96;&#96;) to refer to `argument`s in function descriptions
 198 | +- Backticks aren't required when referring to a Function() that Doxygen already knows about; it will build a hyperlink automatically
 199 | +- Avoid linking to external documentation; links can break
 200 | +- `STRIP_CODE_COMMENTS = YES` in Doxyfile.in, so if you want a standalone comment to be preserved in the Doxygen-generated source code, it must either not conform to Javadoc or be qualified (e.g. begin with `\file`, etc).

jonatack commented at 4:55 PM on September 26, 2019:

End all or none of these item sentences with a period/full stop, e.g. "."; in this document the other item lists use periods/full stops.

jonatack commented at 4:57 PM on September 26, 2019:

Wrapping lines at 80 or 120 characters for these changes could be nice for source code readability on smaller screens.

jonatack commented at 4:58 PM on September 26, 2019: member

A few suggestions below.
doc: Add to Doxygen documentation guidelines 305182e43e
ch4ot1c force-pushed on Oct 2, 2019

in doc/developer-notes.md:12 in 305182e43e

  23 | -    - [Ignoring IDE/editor files](#ignoring-ideeditor-files)
  24 | +  - [Coding Style (General)](#coding-style-general)
  25 | +  - [Coding Style (C++)](#coding-style-c)
  26 | +  - [Coding Style (Python)](#coding-style-python)
  27 | +  - [Coding Style (Doxygen-compatible comments)](#coding-style-doxygen-compatible-comments)
  28 | +    - [Generating Documentation](#generating-documentation)

ch4ot1c commented at 6:36 AM on October 2, 2019:

VSCode plugin "Markdown All in One" updated the ToC automatically, oops - shall we keep?

laanwj commented at 11:17 AM on November 20, 2019:

TOC updates are welcome, but please keep the original spacing

DrahtBot commented at 3:19 PM on November 19, 2019: member

Needs rebase
DrahtBot added the label Needs rebase on Nov 19, 2019
fanquake commented at 3:18 AM on January 5, 2020: member

Closing "Up for Grabs". There's a couple of improvements here that could be picked up.
fanquake closed this on Jan 5, 2020
fanquake added the label Up for grabs on Jan 5, 2020
in doc/developer-notes.md:18 in 305182e43e
```
  29 | +  - [Development tips and tricks](#development-tips-and-tricks)
  30 | +    - [Compiling for debugging](#compiling-for-debugging)
  31 | +    - [Compiling for gprof profiling](#compiling-for-gprof-profiling)
  32 | +    - [debug.log](#debuglog)
  33 | +    - [Testnet and Regtest modes](#testnet-and-regtest-modes)
  34 | +    - [DEBUG_LOCKORDER](#debuglockorder)
```
jonatack commented at 5:42 AM on January 5, 2020:

The #debug_lockorder link should not have been changed; the changed version no longer works.

fanquake commented at 5:45 AM on January 5, 2020:

There are a couple improvements in the table of contents, but any unneeded formatting changes can be dropped.

jonatack commented at 6:23 AM on January 5, 2020:

Agreed. Minimising.
jonatack commented at 5:43 AM on January 5, 2020: member

Ok, will finish this up.
fanquake removed the label Needs rebase on Jan 5, 2020
fanquake removed the label Up for grabs on Jan 5, 2020
fanquake referenced this in commit ceb789cf3a on Jan 14, 2020
sidhujag referenced this in commit 6987379cd9 on Jan 14, 2020
sidhujag referenced this in commit f5637b90ad on Nov 10, 2020
DrahtBot locked this on Feb 15, 2022

Contributors

Labels

Linked (view graph)

#16947 doc: Doxygen-friendly script/descriptor.h comments #17873 doc: Add to Doxygen documentation guidelines