diff options
author | Jon Layton <me@jonl.io> | 2018-11-28 14:45:50 -0600 |
---|---|---|
committer | Jon Layton <me@jonl.io> | 2018-11-29 11:58:30 -0600 |
commit | a62e6672963f0fd9e31c8a6e252e8230052632ec (patch) | |
tree | 2a057693cb723985e24af5d4b23ab3dcbb42fd6b | |
parent | 60b20c869f8df9a81b5080ebcbe8c9cf4e6b9d77 (diff) | |
download | bitcoin-a62e6672963f0fd9e31c8a6e252e8230052632ec.tar.xz |
docs: Add more Doxygen information to Developer Notes
-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 bb477d4be0..9ba4d7500a 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) @@ -118,10 +118,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++ @@ -154,7 +161,7 @@ int var; //!< Detailed description after the member ``` or -```cpp +```c++ //! Description before the member int var; ``` @@ -174,15 +181,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 --------------------------- |