Fortran-FOSS-Programmers / Fortran-FOSS-Programmers/ford

Subroutine level block (note / todo etc.) not appearing in docs

Open
#200 4 comments 0 reactions 0 assignees View on GitHub
bug enhancement
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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.