3 ms·

hadn't heard of API blueprint -- pretty cool. in addition to tools for documenting interfaces (i.e. APIs), I'm interested in tools that document behavior (both

hadn't heard of API blueprint -- pretty cool. 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.

hobofan 9y ago
> I'm interested in tools that document behavior (both desired & observed) and integrate it back to codebases. > 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 https://deckard.ai, but I feel you could also mean something entirely different. (Disclamier: I know the founders of Deckard very well.)
- awinter-py 9y ago
  By 'behavior' I mean two things: (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.
jacques_chester 9y ago
Some of my colleagues in Pivotal Labs swear by Spring Cloud Contract[0], but I haven't used it in anger myself. It seems to be what you want -- an independent statement of protocol that's shared between server and client codebases, with code-generation to help each. [0] https://github.com/spring-cloud/spring-cloud-contract https://github.com/spring-cloud/spring-cloud-contract

hobofan 9y ago

> I'm interested in tools that document behavior (both desired & observed) and integrate it back to codebases. > 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 https://deckard.ai, but I feel you could also mean something entirely different. (Disclamier: I know the founders of Deckard very well.)

awinter-py 9y ago
By 'behavior' I mean two things: (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.

jacques_chester 9y ago

Some of my colleagues in Pivotal Labs swear by Spring Cloud Contract[0], but I haven't used it in anger myself. It seems to be what you want -- an independent statement of protocol that's shared between server and client codebases, with code-generation to help each. [0] https://github.com/spring-cloud/spring-cloud-contract https://github.com/spring-cloud/spring-cloud-contract