search

pecos / tps

Torch Plasma Simulator
BSD 3-Clause "New" or "Revised" License
8 stars 2 forks source link

Initial doxygen support #186

Closed trevilo closed 1 year ago

trevilo commented 1 year ago

This PR adds basic support for doxygen-generated code documentation. Three items are included:

  1. Support for doxygen in our standard test container (see docker/test/Dockerfile)
  2. A doc target in our build system (from the src directory, see src/Makefile.am)
  3. Some example doxygen comments in the Tps class (see e.g., src/tps.hpp)

The main idea here is just to support documenting the code in this way. Clearly generating good comments and documentation will have to be an ongoing activity.

trevilo commented 1 year ago

@shaering: I'd like to get your thoughts on this before merging since it will be mainly the two of us writing documentation, at least in the short term. A few questions:

  1. Does make doc work for you? Note that you'll have to run ./configure first (b/c the Doxyfile is generated at configure time). If not, what happens?
  2. Regarding style, for the Tps class, I chose to put only brief descriptions in the header with longer descriptions (where necessary) with the source. It doesn't impact the html generated by doxygen. My rationale was that I'd like to keep the headers somewhat compact, because I find them easier to read that way. What do you think? I'm flexible, but it would be nice to adopt a somewhat uniform approach.
  3. Any other thoughts or suggestions?