> Configuration is particularly difficult to document in 2017 -- if you solve that problem you fix a lot of migraines.
Could you expand on those points a bit more? As for the first one, it sounds vaguely like https://deckard.ai, but I feel you could also mean something entirely different. (Disclamier: I know the founders of Deckard very well.)
(1) contractual behavior (what you want/expect) can be marked up in comments that generate docs but are also readable inline in the code.
And (2) actual behavior in the wild from monitoring, tracebacks, profiling. Would be cool if IDEs could drop that next to a function so I can ask 'is this slow', 'does this ever get called'.
Re: configuration I'm saying it's not always clear what a config setting does, and esp. how related config settings combine. Having standard types for configuration would let us generate docs for which part of the program are affected by a config setting; at least provide a starting point for understanding the flag's behavior.
in addition to tools for documenting interfaces (i.e. APIs), I'm interested in tools that document behavior (both desired & observed) and integrate it back to codebases.
In type safety terms, this is like the difference between function signatures that verify inputs & outputs vs something like coq/TLA that can verify more advanced properties of your program.
Configuration is particularly difficult to document in 2017 -- if you solve that problem you fix a lot of migraines.