Documentation Meta Data

When documenting your source files you can provide meta-data at the top of an item's documentation. Meta-data is specified in the same way as in the project file. 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 meta-data will be displayed for procedures, derived types, files, programs, modules, type-bound procedures, and interfaces. It may be displayed in more cases in future. Recognized types of meta-data are:

author

The author of this part of the code.

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.