Functions that are part of a modules public API should provide additional details to the caller to let developers interact with the system in a black box manner.

This ticket is to build up guidelines for what type of information is required, and should be available to developers in a public function's comment header.

Some starting suggestions are:

• Description: Externally visible behavior of the function. This should not describe the implementation
• Arguments: Explanation of each argument
• Return value (if different from WT standard of 0 on success or an error code)
• Pre-conditions:
  • Global state requisites, if any.
  • Concurrency requisites, if any.
• Post-conditions:

• • Global state impacts, if any.
  • Concurrency impacts, if any.
  • Import Error conditions, if any.

• • • Transient error
    • Non recoverable error.

Note that this template should keep as small a surface as possible. We would like to provide suggestions that a developer should think about, but not mandate a long checklist.

Optionally as part of this work we should review an s_all tool that identifies comments needing further documentation. This can be split out if it proves cumbersome.

Definition of done:
An example template for a function header that describes the important features a developer should think about when writing comment headers