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.
