3 ms·

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 re

• thangalin 8mo ago
  > 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/ https://keenwrite.com/
  • moritz 8mo ago
    In the Elixir ecosystem (where documentation is considered a "first-class citizen" in the language), you can run code examples as part of your test suite in a similar fashion ("doctest"): https://elixir-recipes.github.io/testing/doctests/ https://elixir-recipes.github.io/testing/doctests/
    • thangalin 7mo ago
      > documentation is considered a "first-class citizen" How exquisitely Knuthian!