Thierry wrote:
> And now, the architects vs. developers discussion :) > I hear both sides of the argument, and I think both have very valid points. > However, so far we have been following the "architect" way (design upfront and separately from code), > and it's failing miserably. That analysis omits a very important third party: users of the API. One of the reasons for documenting an API separately from the source code that implements it is that it isolates the users from having to understand the implementation. The problem with auto-generating API documentation is that it seldom fosters a proper respect for the value of a stable, consistent API that might evolve to support new features but keeps a consistent approach. The other shortcoming is that it tends to omit behavioral specification, and instead focus on Enumerating fields in requests. The major advantage of generated API documentation is that it can be edited with the same tools as the source code is edited, and it makes a proper distinction between the specification of the API (something that should change very slowly) and tutorial explanations of the API (something where continual improvement should always be welcome). While the build environment does not require it, "API specification files" that were sufficiently segregated from the general source files so as to encourage careful consideration when extending the API would provide the benefit of a single set of tools, and hopefully not create an environment for outside developers where the API is subject to frequent churn. _______________________________________________ Mailing list: https://launchpad.net/~openstack Post to : openstack@lists.launchpad.net Unsubscribe : https://launchpad.net/~openstack More help : https://help.launchpad.net/ListHelp
