diff options
| author | MarcoFalke <falke.marco@gmail.com> | 2019-01-04 11:49:19 +0100 |
|---|---|---|
| committer | MarcoFalke <falke.marco@gmail.com> | 2019-01-04 11:49:29 +0100 |
| commit | fd83c57d6bee7c9ba6e39ca088760f3c11b76eeb (patch) | |
| tree | eb5dcb137c16738bda5cc4a40b8d7de1ec7215e1 | |
| parent | f51aeac5add6cff57a6e9fee62caa34058a4e524 (diff) | |
| parent | a62e6672963f0fd9e31c8a6e252e8230052632ec (diff) | |
Merge #14832: docs: Add more Doxygen information to Developer Notes
a62e667296 docs: Add more Doxygen information to Developer Notes (Jon Layton)
Pull request description:
Update information about Doxygen in `doc/developer-notes.md`.
Alternatively, this could have its own file (like `doc/web-documentation.md`), since there are installation steps included.
For example, I had to run:
```
brew install doxygen graphviz
```
on MacOS, otherwise failures occurred.
This information could also be linked to the `doc/release-process.md`.
Tree-SHA512: 5d77ee83e1b96fde036482b502f676a90a56f3f667753545a7cfba5c2e3b825644bb4cf0f8a84b7f9ba92fa5f2e1cd6ef1e27a94277f43d012355df741f7dd2f
| -rw-r--r-- | doc/developer-notes.md | 31 |
1 files changed, 19 insertions, 12 deletions
diff --git a/doc/developer-notes.md b/doc/developer-notes.md index a6df17ddd8..e0def4ea27 100644 --- a/doc/developer-notes.md +++ b/doc/developer-notes.md @@ -7,8 +7,8 @@ Developer Notes - [Developer Notes](#developer-notes) - [Coding Style (General)](#coding-style-general) - [Coding Style (C++)](#coding-style-c) - - [Doxygen comments](#doxygen-comments) - [Coding Style (Python)](#coding-style-python) + - [Coding Style (Doxygen-compatible comments)](#coding-style-doxygen-compatible-comments) - [Development tips and tricks](#development-tips-and-tricks) - [Compiling for debugging](#compiling-for-debugging) - [Compiling for gprof profiling](#compiling-for-gprof-profiling) @@ -120,10 +120,17 @@ public: } // namespace foo ``` -Doxygen comments ------------------ +Coding Style (Python) +--------------------- + +Refer to [/test/functional/README.md#style-guidelines](/test/functional/README.md#style-guidelines). -To facilitate the generation of documentation, use doxygen-compatible comment blocks for functions, methods and fields. +Coding Style (Doxygen-compatible comments) +------------------------------------------ + +Bitcoin Core uses [Doxygen](http://www.doxygen.nl/) to generate its official documentation. + +Use Doxygen-compatible comment blocks for functions, methods, and fields. For example, to describe a function use: ```c++ @@ -156,7 +163,7 @@ int var; //!< Detailed description after the member ``` or -```cpp +```c++ //! Description before the member int var; ``` @@ -176,15 +183,15 @@ Not OK (used plenty in the current source, but not picked up): // ``` -A full list of comment syntaxes picked up by doxygen can be found at http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html, -but if possible use one of the above styles. - -Documentation can be generated with `make docs` and cleaned up with `make clean-docs`. +A full list of comment syntaxes picked up by Doxygen can be found at https://www.stack.nl/~dimitri/doxygen/manual/docblocks.html, +but the above styles are favored. -Coding Style (Python) ---------------------- +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. -Refer to [/test/functional/README.md#style-guidelines](/test/functional/README.md#style-guidelines). +Before running `make docs`, you will need to install dependencies `doxygen` and `dot`. For example, on MacOS via Homebrew: +``` +brew install doxygen --with-graphviz +``` Development tips and tricks --------------------------- |