aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorfanquake <fanquake@gmail.com>2020-01-14 09:44:44 +0800
committerfanquake <fanquake@gmail.com>2020-01-14 10:02:26 +0800
commitceb789cf3a9075729efa07f5114ce0369d8606c3 (patch)
tree92cf06d99c318368815a7f792f39b07f79da5834
parenta4a93a0badb328c4e54c3ceb7cc29a740bce5e43 (diff)
parentc902c4c0c6a26de8cb69a469503bf4a0bd73903c (diff)
Merge #17873: doc: Add to Doxygen documentation guidelines
c902c4c0c6a26de8cb69a469503bf4a0bd73903c doc: Add to Doxygen documentation guidelines (Jon Layton) Pull request description: Completes the up-for-grabs PR #16948. Changes can be tested here: [doc/developer-notes.md](https://github.com/jonatack/bitcoin/blob/doxygen-developer-notes-improvements/doc/developer-notes.md) Co-authored-by: Jon Layton <me@jonl.io> ACKs for top commit: fanquake: ACK c902c4c0c6a26de8cb69a469503bf4a0bd73903c - quick read, checked the new links work. laanwj: ACK c902c4c0c6a26de8cb69a469503bf4a0bd73903c Tree-SHA512: 3b4cebba23061ad5243b2288c2006bf8527e74c689223825f96a44014875d15b2ab6ff54b8aa342ca657a14cf6ce3ab7d6e25bea5befd91162bc2645a74ddb7e
-rw-r--r--doc/developer-notes.md72
1 files changed, 55 insertions, 17 deletions
diff --git a/doc/developer-notes.md b/doc/developer-notes.md
index b50f552e92..5f91296f57 100644
--- a/doc/developer-notes.md
+++ b/doc/developer-notes.md
@@ -9,6 +9,7 @@ Developer Notes
- [Coding Style (C++)](#coding-style-c)
- [Coding Style (Python)](#coding-style-python)
- [Coding Style (Doxygen-compatible comments)](#coding-style-doxygen-compatible-comments)
+ - [Generating Documentation](#generating-documentation)
- [Development tips and tricks](#development-tips-and-tricks)
- [Compiling for debugging](#compiling-for-debugging)
- [Compiling for gprof profiling](#compiling-for-gprof-profiling)
@@ -35,6 +36,9 @@ Developer Notes
- [Source code organization](#source-code-organization)
- [GUI](#gui)
- [Subtrees](#subtrees)
+ - [Upgrading LevelDB](#upgrading-leveldb)
+ - [File Descriptor Counts](#file-descriptor-counts)
+ - [Consensus Compatibility](#consensus-compatibility)
- [Scripted diffs](#scripted-diffs)
- [Suggestions and examples](#suggestions-and-examples)
- [Release notes](#release-notes)
@@ -138,12 +142,17 @@ For example, to describe a function use:
```c++
/**
- * ... text ...
- * @param[in] arg1 A description
- * @param[in] arg2 Another argument description
- * @pre Precondition for function...
+ * ... Description ...
+ *
+ * @param[in] arg1 input description...
+ * @param[in] arg2 input description...
+ * @param[out] arg3 output description...
+ * @return Return cases...
+ * @throws Error type and cases...
+ * @pre Pre-condition for function...
+ * @post Post-condition for function...
*/
-bool function(int arg1, const char *arg2)
+bool function(int arg1, const char *arg2, std::string& arg3)
```
A complete list of `@xxx` commands can be found at http://www.doxygen.nl/manual/commands.html.
@@ -158,44 +167,73 @@ To describe a class, use the same construct above the class definition:
* @see GetWarnings()
*/
class CAlert
-{
```
To describe a member or variable use:
```c++
-int var; //!< Detailed description after the member
+//! Description before the member
+int var;
```
or
```c++
-//! Description before the member
-int var;
+int var; //!< Description after the member
```
Also OK:
```c++
///
-/// ... text ...
+/// ... Description ...
///
bool function2(int arg1, const char *arg2)
```
-Not OK (used plenty in the current source, but not picked up):
+Not picked up by Doxygen:
```c++
//
-// ... text ...
+// ... Description ...
//
```
+Also not picked up by Doxygen:
+```c++
+/*
+ * ... Description ...
+ */
+```
+
A full list of comment syntaxes picked up by Doxygen can be found at http://www.doxygen.nl/manual/docblocks.html,
but the above styles are favored.
-Documentation can be generated with `make docs` and cleaned up with `make clean-docs`. The resulting files are located in `doc/doxygen/html`; open `index.html` to view the homepage.
+Recommendations:
-Before running `make docs`, you will need to install dependencies `doxygen` and `dot`. For example, on macOS via Homebrew:
-```
-brew install graphviz doxygen
-```
+- Avoiding duplicating type and input/output information in function
+ descriptions.
+
+- Use backticks (&#96;&#96;) to refer to `argument` names in function and
+ parameter descriptions.
+
+- Backticks aren't required when referring to functions Doxygen already knows
+ about; it will build hyperlinks for these automatically. See
+ http://www.doxygen.nl/manual/autolink.html for complete info.
+
+- Avoid linking to external documentation; links can break.
+
+- Javadoc and all valid Doxygen comments are stripped from Doxygen source code
+ previews (`STRIP_CODE_COMMENTS = YES` in [Doxyfile.in](doc/Doxyfile.in)). If
+ you want a comment to be preserved, it must instead use `//` or `/* */`.
+
+### Generating Documentation
+
+The documentation can be generated with `make docs` and cleaned up with `make
+clean-docs`. The resulting files are located in `doc/doxygen/html`; open
+`index.html` in that directory to view the homepage.
+
+Before running `make docs`, you'll need to install these dependencies:
+
+Linux: `sudo apt install doxygen graphviz`
+
+MacOS: `brew install doxygen graphviz`
Development tips and tricks
---------------------------