HN Explorer

Ask HN: Tools to generate coverage of user documentation for code

6 points by tstack ↗ HN
Does anyone know of tools/techniques for generating a coverage report of user documentation over source code? In other words, I'd like to be able to automatically determine when there is documentation missing for an implemented feature or if there is documentation for a feature that was removed.

I'm asking because I've been working on a tool for many years and it's grown large enough that I have a hard time keeping track of what all the parts do and what has and has not been documented. What I'm thinking I'd like to do is add a tag to a piece of source code (C++) and put the corresponding tag in the user docs (RST). Then, during the build, I'd like a report of untagged code, code/docs with matching tags, and code/docs with unmatched tags.

I also feel like there should be at least two levels of documentation to be tracked: 1) the overall feature and 2) fine-details about how the feature behaves under different circumstances. For example, a feature that interacted with the network would have an overall description and some extra notes about how timeouts/retries are handled.

Does anyone have any experience with such a thing or have a similar interest?

6 comments

[ 3.1 ms ] story [ 25.1 ms ] thread
pftg
The most closest tools is Cucumber
westurner
"[Python-Dev] Should set objects maintain insertion order too?" https://mail.python.org/archives/list/python-dev@python.org/... :

> Are there URIs for Big-O notation that could be added as e.g. structured attributes in docstrings or annotations?

Looks like docutils supports bibliographic fields and a `metadata` directive: https://docutils.sourceforge.io/docs/ref/rst/directives.html...

RST field lists: https://docutils.sourceforge.io/docs/ref/rst/restructuredtex...

`sphinx-apidoc -M`: https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html

sphinx-contrib/apidoc re-runs sphinx-apidoc on every build to generate the doc stubs: https://github.com/sphinx-contrib/apidoc

awesome-sphinxdoc: https://github.com/yoloseem/awesome-sphinxdoc

Requirements traceability: https://en.wikipedia.org/wiki/Requirements_traceability

Test coverage: https://en.wikipedia.org/wiki/Code_coverage

...

Someday I'd like to be able to express RDF triples in RST; wherein the preceding heading and/or a specific attribute specify the subject URI and then attr/value pairs are predicate/objects. IDK if that's even necessary for this application where you'd have the dotted-path of the __doc__ string to imply the subject URI?

: https://twitter.com/westurner/status/1384081580218408962 :

  How to express #LinkedData in
  - [ ] LaTeX
  - [x] HTML: RDFa, JSON-LD, Microdata
  - [ ] YAML: YAML-LD
  - [ ] Markdown: MyST-Markdown for executablebooks/jupyter-book (Sphinx roles and directives)
  
  - [ ] reStructuredText (docutils)
westurner
- [ ] SCH: SEON OWL ontology could grow a "Documentation"/"Docstring" rdfs:Class/owl:Class and requisite domains on possibly already covering properties to describe the URI-traceable relations between the artifacts: https://github.com/sealuzh/onts-seon :

> SEON consists of multiple ontologies, for example to describe stakeholders, activities, artifacts, and the relations among all of them. The ultimate goal is to facilitate the implementation of tools that help software engineers to manage software systems over their entire life-cycle.

jupyter-book (Sphinx (docutils), myst-parser, jupyter notebooks) > #879 "Generate OpenGraph metadata for social previews and cards" https://github.com/executablebooks/jupyter-book/issues/879#i...