Ensure all functions have comprehensive, accurate documentation including required tags (@param, @return, @since), clear descriptions that match actual behavior, and explanatory comments for complex logic.
Ensure all functions have comprehensive, accurate documentation including required tags (@param, @return, @since), clear descriptions that match actual behavior, and explanatory comments for complex logic.
Functions should include:
Example of complete documentation:
--- Makes an HTTP GET request to the given URL.
--- Can either return the body or save it to a file.
---
--- @param url string The URL to fetch.
--- @param opts? table Optional parameters:
--- - verbose (boolean|nil): Enables curl verbose output.
--- - retry (integer|nil): Number of retries on transient failures (default: 3).
--- - output (string|nil): If set, path to save response body instead of returning it.
--- @param on_exit? fun(err?: string, content?: string) Optional callback for async execution
--- @return string|boolean|nil Response body on success; `nil` on failure
--- @since 14
function M.get(url, opts, on_exit)
-- Compute positions, set them as extmarks, and store in diagnostic._extmark_id
-- (used by get_logical_location to adjust positions)
once_buf_loaded(bufnr, function()
-- complex logic here
end)
end
Avoid confusing wording, inaccurate descriptions, or missing required documentation tags. Future developers should be able to understand the function’s purpose, parameters, and behavior without studying the implementation.
Enter the URL of a public GitHub repository