Uploaded image for project: 'WiredTiger'
  1. WiredTiger
  2. WT-13414

Provide guideline for function comments that are part of a modules API

    • Type: Icon: Task Task
    • Resolution: Unresolved
    • Priority: Icon: Major - P3 Major - P3
    • None
    • Affects Version/s: None
    • Component/s: Not Applicable
    • Storage Engines
    • 5
    • StorEng - Defined Pipeline

      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

            Assignee:
            y.ershov@mongodb.com Yury Ershov
            Reporter:
            andrew.morton@mongodb.com Andrew Morton
            Votes:
            0 Vote for this issue
            Watchers:
            3 Start watching this issue

              Created:
              Updated: