Hyrum K. Wright <hyrum_wright <at> mail.utexas.edu> writes:
> Thanks. Though I'll probably wait a day or two, to let any dissenters
> make themselves known. :)
-1/2. There are parts of your idea that I like, such as linking to "common
documentation", enumerating all of the errors that can be returned, and
specifying whether parameters are in, out, or in/out, but in general I do not
like the idea of changing the style of documentation to focus on documentation
of the parameters.
I am a new user of the API, so in some ways I think that my initial impression
is representative of others newbies' initial impression of the documentation.
And, my initial impression was that I liked how the all of the parameters were
explained in enough detail to be able to actually use the function. In the case
of `svn_client_checkout3`, for example, I like how the documentation currently
points out that the most important field of the ctx is `notify_func2`. The
proposed idea of simply linking to the documentation of `svn_client_ctx_t`
would not be very helpful to a beginner, I think, because there are *so many*
fields of the `svn_client_ctx_t` structure, and it is not immediately clear
which ones affect the behavior of `svn_client_checkout3`. Also, other details
were trimmed away in the mock-up (e.g.: the basic description went from the
detailed "Checkout a working copy of `URL` at `revision`, looked up at
`peg_revision`, using `path` as the root directory of the newly checked out
working copy, and authenticating with the authentication baton cached in `ctx`"
to "Checkout a working copy from a repository"; the description of
`result_rev` is currently more detailed than in the proposed description).
The use of structures to pass in bundles of parameters is problematic for
the proposed style of documentation, because it is not obvious how the fields
of the bundles of parameters should be listed as parameters. Do
you document `ctx->notify_func2` as an [in] parameter? Also, Julian's example
of `svn_client_checkout2` is another problem with the proposed style.
Received on 2010-09-15 17:20:45 CEST