Documentation Metadata#
When documenting your source files you can provide metadata at the top of an item’s documentation. Metadata is specified in the same way as in the Project File Options. There can not be any other documentation before it; not even a blank line of documentation. This will work:
! Good
type :: cat
!! author: C. MacMackin
!! version: v0.2
!!
!! This data-type represents a cat.
but this won’t:
! Bad
type :: cat
!!
!! author: C. MacMackin
!! version: v0.2
!!
!! This data-type represents a cat.
The metadata will be displayed for procedures, derived types, files, programs, modules, type-bound procedures, and interfaces. It may be displayed in more cases in future.
Metadata keys are letters, numbers, underscores, and dashes followed by a colon. Please also note that anything that looks like metadata will be parsed as such and so won’t appear in the rendered documentation.
Recognized types of metadata are:
date#
The date that this part of the code was written (or that the documentation was written; whichever makes more sense to you).
license#
The license for this part of your code. If you want to provide a link then it will have to be in HTML, as it won’t be processed by Markdown.
version#
The version number (or version name) of this part of the code.
category#
A category for this part of the code. In future, FORD may provide lists of things in each category. Currently it is primarily decorative, although it is used when the documentation is being searched.
summary#
A brief description of this part of the code. If not specified, then FORD will use the first paragraph of the body of your documentation.
deprecated#
If this is present and set to ‘true’ then a label saying “Deprecated” will be placed in the documentation.
display#
Overrides the global display settings specified in the project file. It instructs FORD what items to display documentation for. Options are ‘public’, ‘private’, ‘protected’, or any combination of those three. Additionally, ‘none’ specifies that nothing contained within this item should have its documentation displayed (although the item’s own documentation will still be displayed). The option ‘none’ is ignored in source files. Options will be inherited by any contents of this item.
proc_internals#
Overrides the global setting specified in the project file indicating whether to display the local
variables, derived types, etc. within this procedure. May be true
or false. false is equivalent to settign display: none.
source#
Overrides the global source settings specified in the project file. If ‘true’, then the syntax-highlighted source code for this item will be displayed at the bottom of its page of documentation. Note that this only applies for procedures, programs, and derived types. Further note that FORD will not be able to extract the source code if the name of the item is on a different line from the type of item or is on a line containing semi-colons. Line continuation and semi-colons will also prevent extraction from working if they occur on the closing line of the subroutine. For example:
subroutine &
example (a)
integer, intent(inout) :: a
a = a + 1
return
end subroutine example
However, in the case of procedure’s, the argument list may be on a different line from the item’s name.
If warnings are turned on at the command line or in the project file, then a message will be produced if an item’s source code is not successfully extracted.
graph#
Overrides the global graph settings specified in the project file for this particular entity in the code. If set to ‘false’, it no graphs will be produced on its page of documentation and it will not be included in any of the project-wide graphs which are displayed on list pages.