Use docstrings on user facing API
Closed this issue · 6 comments
I've picked some brains during the "Ebrains Winter of Documentation" this week. All projects use docstrings and automatic doc generation to ensure difference between code and documentation can be 1. assessed/tested and 2. kept small. Larger projects in particular insist on this: manually written docs are not checkable or testable. With people moving in and out, of various levels of expertise, documented code is very helpful.
Also, it's difficult to find any code guideline/best practice list that does not include it (the OCNS Software Dev group is generating their own collection of resources and eventually trainings, Ebrains TC is in the early stages of drafting such guidelines).
I order to be prepared for the end of SGA3, it think we should give this another thought. A lot of expertise will drop out, and having heard how long experienced devs say they took to be comfortable, I think it's a sorely needed feature if we expect a diverse community to pick Arbor up. The earlier we start, the more time we have.
Docstrings are good for documenting APIs, argument lists, etc, however they don't document much of the architecture of the system, which is the most difficult thing for new developers to understand.
They make it easier for a developer who is spelunking around the code to try to reverse engineer the architecture, but if we want to invest in documentation that directly addresses the architecture.
In the Winter of Documentation it became clear pretty much all projects present have gravitated towards separating user and developer documentation. It is apparently the best way for many project to deal with the different concerns and levels a viewer of the documentation has. Hidden or incomplete API references communicate a sense of incompleteness and that is something to avoid!
Currently our Concepts section serves both, and quite well, users and developers. The API pages to me then are the natural place for this, both from your perspective and the perspective of being able to maintain the documentation without manual review of the API pages.
In this Discussion, question 3 (last) is due to a confusing function signature.
Hi @brenthuisman,
any updates here? Docstrings are great and we started using them, do you consider this done?
- Python: OK, although there are problems with integration between Sphinx and Pybind11 (who generates signatures), leading to us needing to manually keep text documentation (
/doc) and source documentation (/python) in sync. See #1172 - C++: Much progress needed :) A choice for an annotation format for starters. Dev docs are starting to shape up, and although for many cases a better resource than docstrings, I think it'd be good to make a choice and start adding annotations to C++ code too.
Our Python API is pretty complete in terms of doc strings.