Public API documentation

["Hyrum K. Wright" <hy...@mail.utexas.edu>]

I've been thinking about ways that our API documentation could be made
a bit cleaner.

Currently, we use a lot of prose to describe APIs, their parameters,
and other nuances.  I find this approach rather unique, and in some
ways obfuscating.  We have great documentation in that we cover a lot
of ground, but I wonder if we can be more consistent and clear.

For instance, look at the description of svn_client_checkout3():
http://people.apache.org/~hwright/svn/doc/api/trunk/group__clnt__wc__checkout.html#ga31e87d0db53bf1158eaceb6552c63bae

It's is really difficult to determine what each parameter does or what
possible errors are returned, without reading the entire docstring.
Maybe that's intended, but perhaps a strategy which enumerates the
parameters would be a bit better.  I've mocked up with this may look
like:
http://people.apache.org/~hwright/svn/doc/api/temp/group__clnt__wc__checkout.html#ga31e87d0db53bf1158eaceb6552c63bae

You'll note that there isn't a complex discussion of client contexts,
depth, or peg revisions, but rather links to a common location where
such concepts can be discussed in-depth.  I've also tried to detect
the various errors which may be returned, and enumerate them
specifically, rather than buried in the prose description of the API.
I think this strategy will lead to more consistent and maintainable
documentation across the project (and easier identifiable deviations
from standard behavior).

Thoughts?

-Hyrum

Re: Public API documentation

[Uwe Stuehler <su...@bsdx.de>]

On Mi, 2010-09-15 at 10:35 +0100, Julian Foad wrote:
> Hyrum K. Wright wrote:
> > I've been thinking about ways that our API documentation could be made
> > a bit cleaner.
...
> > Thoughts?
> > 
> > -Hyrum
> 
> +1.
> 
> You know what, I've been a bit skeptical of the list-of-params style of
> documentation, as sometimes I've seen "documentation" that says "@param
> revision - the revision number; @param path - the path", without saying
> the path of what, what kind of path, relative to what.
> 
> But your mock-up is very good.  I particularly like that it refers to
> the canonical definitions of depth, client_ctx (saying which parts of
> that are relevant) and operative/peg revisions, instead of trying to
> explain them yet again in yet another way.

Indeed, I find it very good and it adds a lot of value by referencing
important concepts and giving a concise list of return values.

This style also feels a lot easier to handle, in my opinion, if I refer
to the documentation in order to use other language bindings.  Could be
due to fewer uses of C syntax and marking parameters as in/out.  I don't
feel burdened with the task to read everything and can quickly check a
single parameter or return value's description.

> This style won't fit all functions - for example, I don't think it would
> be useful to rewrite the doc string of svn_client_checkout2() which is
> currently:
> 
>   "Similar to svn_client_checkout3() but with allow_unver_obstructions
> always set to FALSE, and depth set according to recurse: if recurse is
> TRUE, depth is svn_depth_infinity, if recurse is FALSE, depth is
> svn_depth_files."

I think that is true. It would fit many of the current version functions
but describing differences to older versions, for example, may be easier
done with a descriptive text.

Cheers,
Uwe

Re: Public API documentation

["Hyrum K. Wright" <hy...@mail.utexas.edu>]

On Wed, Sep 15, 2010 at 5:07 PM, Daniel Trebbien <dt...@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

Re: Public API documentation

[Daniel Trebbien <dt...@gmail.com>]

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.

Re: Public API documentation

["Hyrum K. Wright" <hy...@mail.utexas.edu>]

On Wed, Sep 15, 2010 at 11:35 AM, Julian Foad <ju...@wandisco.com> wrote:
> Hyrum K. Wright wrote:
>> I've been thinking about ways that our API documentation could be made
>> a bit cleaner.
>>
>> Currently, we use a lot of prose to describe APIs, their parameters,
>> and other nuances.  I find this approach rather unique, and in some
>> ways obfuscating.  We have great documentation in that we cover a lot
>> of ground, but I wonder if we can be more consistent and clear.
>>
>> For instance, look at the description of svn_client_checkout3():
>> http://people.apache.org/~hwright/svn/doc/api/trunk/group__clnt__wc__checkout.html#ga31e87d0db53bf1158eaceb6552c63bae
>>
>> It's is really difficult to determine what each parameter does or what
>> possible errors are returned, without reading the entire docstring.
>> Maybe that's intended, but perhaps a strategy which enumerates the
>> parameters would be a bit better.  I've mocked up with this may look
>> like:
>> http://people.apache.org/~hwright/svn/doc/api/temp/group__clnt__wc__checkout.html#ga31e87d0db53bf1158eaceb6552c63bae
>>
>> You'll note that there isn't a complex discussion of client contexts,
>> depth, or peg revisions, but rather links to a common location where
>> such concepts can be discussed in-depth.  I've also tried to detect
>> the various errors which may be returned, and enumerate them
>> specifically, rather than buried in the prose description of the API.
>> I think this strategy will lead to more consistent and maintainable
>> documentation across the project (and easier identifiable deviations
>> from standard behavior).
>>
>> Thoughts?
>>
>> -Hyrum
>
> +1.
>
> You know what, I've been a bit skeptical of the list-of-params style of
> documentation, as sometimes I've seen "documentation" that says "@param
> revision - the revision number; @param path - the path", without saying
> the path of what, what kind of path, relative to what.
>
> But your mock-up is very good.  I particularly like that it refers to
> the canonical definitions of depth, client_ctx (saying which parts of
> that are relevant) and operative/peg revisions, instead of trying to
> explain them yet again in yet another way.
>
> I also like the way we can easily check whether the correct set of
> parameters is documented.  In the past we have often changed function
> parameters (when revving the function, or just renaming existing params)
> and have failed to notice that the doc string no longer refers to the
> real params.

And we get the added benefit of allowing doxygen to help us by
identifying undocumented or documented-but-not-existent parameters.

> This style won't fit all functions - for example, I don't think it would
> be useful to rewrite the doc string of svn_client_checkout2() which is
> currently:
>
>  "Similar to svn_client_checkout3() but with allow_unver_obstructions
> always set to FALSE, and depth set according to recurse: if recurse is
> TRUE, depth is svn_depth_infinity, if recurse is FALSE, depth is
> svn_depth_files."

Agreed.  That is essentially "inherit the docstring for checkout3(),
but with the following delta".

> So +1 on starting to use this style and on committing your
> svn_client_checkout3() doc string to start the ball rolling.

Thanks.  Though I'll probably wait a day or two, to let any dissenters
make themselves known. :)

-Hyrum

Re: Public API documentation

["C. Michael Pilato" <cm...@collab.net>]

On 09/15/2010 05:35 AM, Julian Foad wrote:
> Hyrum K. Wright wrote:
>> I've been thinking about ways that our API documentation could be made
>> a bit cleaner.

[...]

>> It's is really difficult to determine what each parameter does or what
>> possible errors are returned, without reading the entire docstring.
>> Maybe that's intended, but perhaps a strategy which enumerates the
>> parameters would be a bit better.  I've mocked up with this may look
>> like:
>> http://people.apache.org/~hwright/svn/doc/api/temp/group__clnt__wc__checkout.html#ga31e87d0db53bf1158eaceb6552c63bae

I would suggest that yes, it is intended that folks read the entire
docstring for a function before using it.  But I "get" that sometimes it
might be nice to more quickly lookup a particular parameter's general
meaning without swimming through tons of context.

Julian Foad wrote:
> But your mock-up is very good.  I particularly like that it refers to
> the canonical definitions of depth, client_ctx (saying which parts of
> that are relevant) and operative/peg revisions, instead of trying to
> explain them yet again in yet another way.

+1

> I also like the way we can easily check whether the correct set of
> parameters is documented.

Yup.


-- 
C. Michael Pilato <cm...@collab.net>
CollabNet   <>   www.collab.net   <>   Distributed Development On Demand

Re: Public API documentation

[Julian Foad <ju...@wandisco.com>]

Hyrum K. Wright wrote:
> I've been thinking about ways that our API documentation could be made
> a bit cleaner.
> 
> Currently, we use a lot of prose to describe APIs, their parameters,
> and other nuances.  I find this approach rather unique, and in some
> ways obfuscating.  We have great documentation in that we cover a lot
> of ground, but I wonder if we can be more consistent and clear.
> 
> For instance, look at the description of svn_client_checkout3():
> http://people.apache.org/~hwright/svn/doc/api/trunk/group__clnt__wc__checkout.html#ga31e87d0db53bf1158eaceb6552c63bae
> 
> It's is really difficult to determine what each parameter does or what
> possible errors are returned, without reading the entire docstring.
> Maybe that's intended, but perhaps a strategy which enumerates the
> parameters would be a bit better.  I've mocked up with this may look
> like:
> http://people.apache.org/~hwright/svn/doc/api/temp/group__clnt__wc__checkout.html#ga31e87d0db53bf1158eaceb6552c63bae
> 
> You'll note that there isn't a complex discussion of client contexts,
> depth, or peg revisions, but rather links to a common location where
> such concepts can be discussed in-depth.  I've also tried to detect
> the various errors which may be returned, and enumerate them
> specifically, rather than buried in the prose description of the API.
> I think this strategy will lead to more consistent and maintainable
> documentation across the project (and easier identifiable deviations
> from standard behavior).
> 
> Thoughts?
> 
> -Hyrum

+1.

You know what, I've been a bit skeptical of the list-of-params style of
documentation, as sometimes I've seen "documentation" that says "@param
revision - the revision number; @param path - the path", without saying
the path of what, what kind of path, relative to what.

But your mock-up is very good.  I particularly like that it refers to
the canonical definitions of depth, client_ctx (saying which parts of
that are relevant) and operative/peg revisions, instead of trying to
explain them yet again in yet another way.

I also like the way we can easily check whether the correct set of
parameters is documented.  In the past we have often changed function
parameters (when revving the function, or just renaming existing params)
and have failed to notice that the doc string no longer refers to the
real params.

This style won't fit all functions - for example, I don't think it would
be useful to rewrite the doc string of svn_client_checkout2() which is
currently:

  "Similar to svn_client_checkout3() but with allow_unver_obstructions
always set to FALSE, and depth set according to recurse: if recurse is
TRUE, depth is svn_depth_infinity, if recurse is FALSE, depth is
svn_depth_files."

So +1 on starting to use this style and on committing your
svn_client_checkout3() doc string to start the ball rolling.

- Julian