1 Documenting your code {#documenting}
4 %IMP is documented
using `doxygen`. See
5 [Documenting your code in doxygen](http:
6 to
get started. We use `
7 You are encouraged to use Doxygen
's
8 [markdown support](http://www.doxygen.nl/manual/markdown.html) as much as possible.
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.
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
18 void messy_poorly_thought_out_function();
21 We provide a number of extra Doxygen commands to aid in producing nice
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`.
29 - To mark a method as not having been well tested yet, use
30 `\\untested{Classname}`.
32 - To mark a method as not having been implemented, use
33 `\\unimplemented{Classname}`.
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.
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.