logoalt Hacker News

petcat • yesterday at 7:51 PM • 1 reply • view on HN

Out-of-band docs have always been a constant source of frustration and discrepancies. It's really difficult to keep readme.com docs updated with actual code releases because there's no hard constraint preventing one from updating without the other. It just relies on "convention".

Replies

thangalin • yesterday at 8:01 PM

> difficult to keep [...] docs updated with actual code

I used my software and R Markdown documents to help address such problems. In the source code, you have:

    // DOC SNIPPET BEGAN: example_api_usage
    /**
     */
    function amazing_function( char life, long universe, string everything ) {
    } 
    // DOC SNIPPET ENDED
In the R Markdown you write an R function to parse all snippets, then refer to snippets by name. If the snippet can't be found, building the documentation fails, and noisily breaks a CI/CD pipeline.

What's nice is that you can then use this to parse C++ definitions into Markdown tables to render nicely formatted content.

The general idea is that you can have "living" documentation reference source code and break on mismatch. Whether you use knitr/pandoc or python or KeenWrite/R Markdown[1] is an implementation detail.

[1]: https://keenwrite.com/

➕ show 1 reply