Header files and inline documentation

Doxygen is a documentation generator. It reads specially formatted inline comments and generates, e.g., HTML.

Example:

#pragma once
/** @file caesar.h
 *  @brief Caesar cipher only defined for upper-case ASCII
 */

#ifndef CAESAR_SHIFT
#define CAESAR_SHIFT 3 /**< Shift for each letter. */
#endif

/**
 * @brief Encrypt an upper-case string with Caesar in-place
 *
 * @note Non-uppercase characters are ignored. Uses @ref CAESAR_SHIFT.
 * @return Same string encrypted
 */
char *caesar_encrypt(char *plaintext);
/**
 * @brief Encrypt a single upper-case character
 *
 * @note Non-uppercase characters are ignored
 */
char caesar_encrypt_char(char plaintextc, char shift);

/**
 * @brief Decrypt an upper-case string with Caesar in-place
 *
 * @note Non-uppercase characters are ignored. Uses @ref CAESAR_SHIFT.
 * @return Same string encrypted
 */
char *caesar_decrypt(char *ciphertext);
/**
 * @brief Decrypt a single upper-case character
 *
 * @note Non-uppercase characters are ignored
 */
char caesar_decrypt_char(char ciphertextc, char shift);

The comments on the top of a declaration are also automatically shown by the language server. They don’t have to follow Doxygen syntax:

Fig. 16 Hovering on a function shows inline documentation.