Comment by marcosdumay
4 days ago
> what you're asking for is type definitions
It's the API specification. It's not just the functions and their parameters, it's also an explanation of what they do.
> I'm much less interested in the specific arguments, and I'm very interested in "Capabilities"
And that's exactly what an API specification provides you, and that examples do not. Examples only tell you how to use the API on the same way that the author is using it.
I really want both. I can follow examples and read specifications, but i likely want the simplest example first if I'm using a tool, and then the specifications after i've used it a few times.
it's much harder to imagine everything a tool can do with only the specs, and I'm not clear what things I'm missing. Examples make it concrete