On Wed, Sep 15, 2010 at 5:07 PM, Daniel Trebbien <dtrebbien_at_gmail.com> wrote:
> 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
Actually, the important fields are notify_func2, and the auth_baton,
but the current docs make zero mention of the later.
> 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`.
Then we need to make it clear, such as saying "used for authentication
and notification". In the client context docs, we'd have something
like "if used for authentication..." and "if used for
notification...".
> 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).
But that's my point. We spent a lot of time writing the *exact same*
documentation for many APIs. Instead of write "of `URL` at
`revision`, looked up at `peg_revision`, using `path` as the root
directory of the newly checked out working copy," for every single API
which takes a URL, peg revision and revision, I'd prefer to only write
that text once, where it can then be referenced from every API which
needs it. (Kinda like a documentation subroutine. :)
In the bits that are referenced often, such as svn_client_ctx_t, it
would be important that we are explicit about what the members mean,
and what they do, much more than we currently are. And I pray we're
currently being consistent on how we use those members between APIs.
By the way, I think your perspective is very valuable. It's been a
long time since I was new to the Subversion APIs, and have since lost
that perspective. But I also use the API documentation on a regular
basis, demonstrating that we should cater to both new and "old" API
consumers.
> 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?
We document all of the client context as an [in] parameter. But yeah,
having a massive bunch of stuff is not very conducive for
documentation (or for maintenance, it turns out).
> Also, Julian's example
> of `svn_client_checkout2` is another problem with the proposed style.
We'd leave that as-is.
A side goal of this little project is to make the documentation better
parable, so that automagic docs of the bindings, for instance, could
be generated. But that's really tangential to human readability.
Thanks for the feedback,
-Hyrum
Received on 2010-09-15 20:51:06 CEST