Ensure all function documentation accurately reflects the actual code behavior and includes complete, properly formatted descriptions of parameters and return values.
Key requirements:
Match function signatures: Documentation must accurately describe what the function actually does and returns. A void function should not claim to “return true”.
@param[in/out] name Description
with two spaces after name@return
as the start of a sentence, not embedded within it:
// Incorrect:
/// @return Always return 0.
// Correct:
/// @return always 0.
/// Get information about Num/Caps/Scroll Lock state
///
/// To be used in nvim_get_keyboard_mods_state() API function.
///
/// @param[out] dict Pointer to dictionary where information about modifiers
/// is to be dumped.
/// @param[out] err Location where error message is to be saved, set to NULL
/// if no error.
///
/// @return true in case of error, false otherwise.
This ensures developers can rely on documentation to understand function behavior without needing to read the implementation.
Enter the URL of a public GitHub repository