Doxygen?

[donnaaboise]

Originally reported by: Donna Calhoun (Bitbucket: donnaaboise, GitHub: donnaaboise)

---

Get a start on documentation?

---

• Bitbucket: https://bitbucket.org/donnaaboise/forestclaw/issue/64

[donnaaboise]

Original comment by Carsten Burstedde (Bitbucket: cburstedde, GitHub: cburstedde):

---

This can be worked on anytime by anyone.

[donnaaboise]

Original comment by Carsten Burstedde (Bitbucket: cburstedde, GitHub: cburstedde):

---

There is now a Doxyfile.in that lists the INPUT directories (recursively, currently src, may want to add others). To see what it does, just type make doxygen in the build directory. Ideally, all error messages that it prints should eventually be resolved. The result can be browsed under doxygen/html/index.html. To activate documentation per-file, it is necessary to add a

/** \file actual_file_name.h
 * Write extended documentation here.
 * This can have multiple lines.
 * See the allowed markdown syntax in the doxygen web page.
 */

comment block at the top. Otherwise it is ignored and will not be clickable.

We're good to go, it just remains to keep editing the doxygen comments.

[donnaaboise]

Original comment by Carsten Burstedde (Bitbucket: cburstedde, GitHub: cburstedde):

---

You can take a look at how doxygen works for p4est. Hit make doxygen in the build directory. Fairly easy to set up -- we just need a Doxyfile.in with some edits and a Makefile rule.

We'd have to decide though which directories shall be doxygenated.

[cburstedde]

We have done a lot of work on the libsc doxygen system, and some on p4est. With upcoming merges, the structure there may be used as guidelines to expand on the ForestClaw documentation.

Note that we rely on several configure-time variables such as @PACKAGE_NAME@. These are automatically replaced by autoconf. With CMake, we need an additional filter step to substitute all of these in Doxyfile.in to create Doxyfile.