Re:
https://www.industrialempathy.com/posts/design-docs-at-googl...> ... sketching out that API is usually a good idea. In most cases, however, one should withstand the temptation to copy-paste formal interface or data definitions into the doc as these are often verbose, contain unnecessary detail and quickly get out of date.
Using R Markdown (or any Turing Complete documentation system), it's possible to introduce demarcations that allow the source code snippets to be the literal source of truth:
// DOCGEN-BEGIN:API_CLASS_NAME
/**
*
*
* @param arg
* @return
*/
uint8_t method( type arg );
// DOCGEN-ENDED:API_CLASS_NAME
Use a GPT to implement a parser for snippets in a few minutes. Then invoke the function from the living document for given a source file, such as:
`r#
snippets -> parse.snippets( "relative/path/to/ClassName.hpp" );
docs -> parse.api( snippets[[ "API_CLASS_NAME" ]] );
export.api( docs );
`
The documentation now cannot ever go stale with respect to the source code. If the comments are too verbose, simplify and capture implementation details elsewhere (e.g., as inline comments).
In one system I helped develop, we were asked to document what messages of a standard protocol were supported. The only place this knowledge exists is in a map in the code base. So instead of copy/pasting that knowledge, we have:
MessageMap MESSAGE_MAP = {
// DOCGEN-BEGIN:SUPPORTED_MESSAGES
{ MessageType1, create() },
{ MessageType2, create() },
...
// DOCGEN-ENEDED:SUPPORTED_MESSAGES
}
And something like:
`r#
snippets -> parse.snippets( "relative/path/to/MessageMap.hpp" );
df -> parse.messages( snippets[[ "SUPPORTED_MESSAGES" ]] );
export.table( df );
`
This snippet is parsed into an R dataframe. Another function converts dataframes into Markdown tables. Changing the map starts a pipeline that rebuilds the documentation, ensuring that the documentation is always correct with respect to the code.
If a future developer introduces an unparseable change, or files are moved, or R code breaks, the documentation build pipeline fails and someone must investigate before the change goes onto main.
Shameless self-plug: The R Markdown documentation system we use is my FOSS application, KeenWrite; however, pandoc and knitr are equally capable.
https://keenwrite.com/