ford

ford copied to clipboard

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

As you say, this is intentional behaviour. FORD is designed so that, on the module page, only the first paragraph of documentation is shown for each subroutine/function (or alternatively whatever is specified in the "summary" metadata). A "read more" link could be useful. The fact that no summary is shown when the first paragraph is a bug/note etc. would be an oversight on how I was extracting the summary--thanks for alerting me to it. I'll fix this and add a "read more" link in an upcoming release.

On 03/03/17 14:06, David Dickinson wrote:

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 |

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/cmacmackin/ford/issues/200, or mute the thread https://github.com/notifications/unsubscribe-auth/AHxJPRDOQo4gTEfSloScbByJ9IiCXsyJks5riB5ZgaJpZM4MSS8k.

-- Chris MacMackin cmacmackin.github.io https://cmacmackin.github.io

Brilliant, thanks for clarifying this and your fast response. Shall I leave this issue open as a reminder/reference for the summary extraction.

Should I create a new feature-request issue for the "read more" or is this issue enough?

Just leave this issue open.

On 03/03/17 14:24, David Dickinson wrote:

Brilliant, thanks for clarifying this and your fast response. Shall I leave this issue open as a reminder/reference for the summary extraction.

Should I create a new feature-request issue for the "read more" or is this issue enough?

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/cmacmackin/ford/issues/200#issuecomment-283965826, or mute the thread https://github.com/notifications/unsubscribe-auth/AHxJPQbC0BsSaWREoikPHqXFikvfPP0Gks5riCKYgaJpZM4MSS8k.

-- Chris MacMackin cmacmackin.github.io https://cmacmackin.github.io

However I go about fixing this should also deal with #223.