Fortran-FOSS-Programmers / Fortran-FOSS-Programmers/ford
Subroutine level block (note / todo etc.) not appearing in docs
- Dominant language
- Python
- Stars
- 458
- Forks
- 138
- PR merge metrics
- No merged PRs in 30d
Description
Apologies if this has already been raised or is covered anywhere else, but I couldn't find any references to this.
I'm trying to add some `@todo` and `@note` blocks to subroutine documentation but these don't appear in the final documentation in a few places (as in all the text is absent, not just the block isn't highlighted). When these appear in the module level documentation comments they do appear and are correctly formatted etc. This note block **does** appear on the documentation page for the subroutine itself (i.e. when clicking on the subroutine name on the Procedures index page).
I guess that this "omission" is intentional, in order to avoid cluttering up the module page etc. but it might be nice to have a flag to control this or maybe even provide a summary in the module based description of the subroutine (e.g. after the description say something like "2 notes and 1 bug", to indicate to the reader that they better go to the subroutine's page for the full details).
One related potential side issue of this is that procedures documented exclusively with these blocks will have no documentation shown on the procedures/modules pages *but* will not trigger the "no documentation" warning when building with `--warn`.
A simple example module which should demonstrate (untested) these issues is as follows
```
!> This is my module documentation
!! @note This note will appear in the module documentation
module testing
contains
!> This is my subroutine documentation
!! @todo Work out why this block doesn't appear in the documentation of the subroutine when
!! browsing the module page. It doesn't appear in the description column on the Procedures
!! page either. It does appear on the in-depth procedure page (i.e. `html/proc/documentMePlease.html`).
subroutine documentMePlease
end subroutine documentMePlease
!> @note No documentation will be shown for this routine in the module/procedure page
!! but the usual warning is not generated. This may be understandable as this note should
!! appear on the subroutine specific page, but does mean that a build without warnings can
!! still have a number of "empty" entries throughout the docs.
subroutine noValidDocumentationButNoWarn
end subroutine noValidDocumentationButNoWarn
end module testing
```
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.