search

LLNL / serac

Serac is a high order nonlinear thermomechanical simulation code
BSD 3-Clause "New" or "Revised" License
182 stars 33 forks source link

Improve Doxygen docs #791

Open samuelpmishLLNL opened 2 years ago

samuelpmishLLNL commented 2 years ago

I just noticed that some of our doxygen docs pages aren't rendering correctly, for example

https://serac.readthedocs.io/en/latest/doxygen/html/classserac_1_1SolidFunctional.html

I suspect this is because of the fact the initial doxygen block comment is on a forward-declared class. There's also some discussion on the doxygen git repo here that may be relevant, relating to a bug with generating documentation for forward-declared class templates being fixed in v1.8.19

samuelpmishLLNL commented 2 years ago

update: it looks like the documentation for these classes is being generated after all, but it's hard to find: https://serac.readthedocs.io/en/latest/doxygen/html/classserac_1_1SolidFunctional_3_01order_00_01dim_00_01Parameters_3_01parameter__space_8_8_8_01_49c3ace0b4f45d5b9a33c01aae45ca535.html

The landing page https://serac.readthedocs.io/en/latest/doxygen/html/ only contains links to the deprecated physics modules, and the entry for SolidFunctional still points to the (empty) forward declaration.

samuelpmishLLNL commented 1 year ago

Also: @white238 noticed that some of our doxygen comment blocks are missing @return statements, but it seems doxygen is not issuing warnings about that.