Documentation Guide

Document the interface - Explain the implementation

• Document what is done in function interfaces
• Document the purpose of a function using interface comments
• Describe how things are done by function code (adhered to #202206171004)
• Describe why things are done using code comments (additionally the other alternatives that were discarded)

Note: It is best to use 202207132124# such as Doxygen (C++ and others) and Javadoc (Java) to generate the documentation automatically.

Note: If you are unsure about the behaviour of the function, write down your assumption and test them.

Note: Treat documentation as one of the views# of the code base.

Note: Preferably documenting in one of the markup languages such as DocBook, Markdown, LaTeX etc. which could be easily converted into other formats, such as PDF, troff, slide shows, HTML etc., using tools like provided DSSL processor and Pandoc.

Note: Always prefer web publishing as the main documentation publishing since it will be always up-to-date.

Note: Make sure the documentation is in good style and easy to read in terms of visual presentation. It is recommended by Hunt et al. to involve readers with early drafts.

General

For documenting the requirements, try using use case templates or diagrams. They are effective mediums for communication, especially for the non-technical people. The Pragmatic Programmer showed an example use case based on Cockburn’s template:

Use case diagrams can be as simple as the following:

❌ Maintain a glossary where specific terms and vocabularies, especially those are used frequent in the project, are defined in order to prevent misunderstanding.

C/C++

The interface must be documented thoroughly in C/C++ as follows:

/**
 ** @brief use the Heron process to approximate @a a to the power of `1/k`
 **
 ** Or in other words this compute the @f$k^{th}@f$ root of @a a.
 ** As a special feature, if @a k is `-1` it computes the multiplicative inverse
 ** of @a a.
 **
 ** @param a must be greater than `0.0`
 ** @param k should not be `0` and otherwise be between
 ** `DBL_MIN_EXP*FLT_RDXRDX` and
 ** `DBL_MAX_EXP*FLT_RDXRDX`
 **
 ** @see FLT_RDXRDX
 **/
double heron(double a, signed k);

Note: Write codes literally. Choose variable names that are meaningful.

Note: The control flow should be obvious.

Note: Write macro in a way that it will not change the control flow in an unexpected way.

Note: Avoid global variable and use 202202081524 as much as possible.

Rust

Rust use documentation string /// and doc string //! for rustdoc to output the comments as HTML. The documentation string could be treated as a Markdown section, and all the codes written in the code fence could be run by cargo test.

//! # My Crate
//!
//! `my_crate` is a collection of utilities to make performing certain
//! calculations more convenient.

/// Adds one to the number given.
///
/// # Examples
///
/// ```
/// let arg = 5;
/// let answer = my_crate::add_one(arg);
///
/// assert_eq!(6, answer);
/// ```
pub fn add_one(x: i32) -> i32 {
    x + 1
}

Other than Examples, there are three more optional sections that we could elaborate further: Panics, Errors (function return Result) and Safety (unsafe function).