IMP logo
IMP Manual  for IMP version 2.16.0
documenting.md
1 Documenting your code {#documenting}
2 =====================
3 
4 %IMP is documented using `doxygen`. See
5 [Documenting your code in doxygen](http://www.doxygen.nl/manual/docblocks.html)
6 to get started. We use `//!` and `/**` ... `*/` blocks for documentation.
7 You are encouraged to use Doxygen's
8 [markdown support](http://www.doxygen.nl/manual/markdown.html) as much as possible.
9 
10 Python code should provide Python doc strings. We automatically convert these
11 into a form Doxygen can parse, so you can use Doxygen commands in them.
12 
13 All headers not in internal directories are parsed through
14 `doxygen`. Any function that you do not want documented (for example,
15 because it is not well tested), hide by surrounding with
16 
17  #ifndef IMP_DOXYGEN
18  void messy_poorly_thought_out_function();
19  #endif
20 
21 We provide a number of extra Doxygen commands to aid in producing nice
22 %IMP documentation.
23 
24 - To mark that some part of the API has not yet been well planned and may change
25  use `\\unstable{Classname}`. The documentation will include a disclaimer
26  and the class or function will be added to a list of unstable classes. It is
27  generally better to simply hide such things from `doxygen`.
28 
29 - To mark a method as not having been well tested yet, use
30  `\\untested{Classname}`.
31 
32 - To mark a method as not having been implemented, use
33  `\\unimplemented{Classname}`.
34 
35 Each %IMP module has a top-level `%README.md` which is also parsed
36 by Doxygen; it includes the names of the authors and
37 a description of what the module is supposed to do.
38 
39 Building the target `IMP-doc` (e.g. by running `make IMP-doc`) will build
40 documentation for all of the modules, while the `IMP.foobar-doc` target
41 will build documentation only for the `foobar` module.