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 not empty 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. ####source Overrides the global source settings specified in the project file. If 'true', then the 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.