openstack team mailing list archive

[Jay Pipes <jaypipes@xxxxxxxxx>]

On Tue, Oct 25, 2011 at 6:34 PM, Caitlin Bestler
<Caitlin.Bestler@xxxxxxxxxxx> wrote:
> WADL sounds like a wonderful validation tool.
>
> But shouldn’t our primary goal be finding a consistent way to describe the
> APIs for *application developers*.
>
> Syntax tools, whether ancient notations like BNF or the latest XML
> concoction only tell you the syntax of the operation.
>
> There also has to be consistent information that provides information to the
> reader as to when and why they would use this specific operation, not just how to format it.
>
> There is also a tendency of syntax oriented tools to omit vital state
> information,  particularly the expected sequence of operations.

+1. API documentation is more than just the inputs, outputs, methods
and parameters. The sequence of operations that may occur, whether
something is async or not, what state changes may occur for resources
over a series of method calls, etc, all are things that WADL doesn't
scratch...

Personally, I'm looking forward to working with Anne to make the
OpenStack Image API docs pretty awesome. WADL is great for
machine-readable validation, but humans are just as important
consumers of docs :)

-jay

-jay