search

cholla-hydro / cholla

A GPU-based hydro code
https://github.com/cholla-hydro/cholla/wiki
MIT License
60 stars 32 forks source link

Remove \fn in Doxygen comments where possible #263

Open alwinm opened 1 year ago

alwinm commented 1 year ago

According to the Doxygen manual, quoted below:

https://doxygen.nl/manual/commands.html#cmdfn

This command is only needed if a comment block is not placed in front (or behind) the function declaration or definition.

If your comment block is in front of the function declaration or definition this command can (and to avoid redundancy should) be omitted. Warning: Do not use this command if it is not absolutely needed, since it will lead to duplication of information and thus to errors.

I think it would improve our existing comments to adopt the standard of omitting redundant \fn commands, which also means removing it wherever possible. I hope to receive feedback on this proposal before any action is taken.

bcaddy commented 1 year ago

I don't have any strong opinions on this, it's fine with me and is an easily automated fix.

Maybe a hack session/workshop on Doxygen would benefit the group. I'd really like to see documentation become standard on all new (and old) code but Doxygen can be a bit confusing when you first start.