[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

Re: API documentation wanted (for Python in particular)

From: <kfogel_at_collab.net>
Date: 2006-03-13 05:02:51 CET

Paul Koning <pkoning@equallogic.com> writes:
> I think part of the reason I feel that way is that there is not the
> slightest hint of ANY description anywhere that I can find to get a
> person started in this direction.

When I said "looks like you'll have to write it", what I meant was:

We need you to remember the places where you expected to find
documentation or pointers to documentation, and it'd be great if you
could help us fix those places so they contain what you expected.

If you don't have time for that level of involvement, that's
understandable. However, I would ask then that you not complain *too*
hard. We're not in possession of some magic potion that we can
sprinkle over the project to make everything be perfectly organized.
We need involvement -- yours and others' -- to make things go right.
Most people here are volunteering their time (disclaimer: I'm not,
CollabNet pays me to work on Subversion... but then, I've got plenty
of stuff on my plate and it's 11:45pm right now, so you could say I'm
volunteering my time at this particular moment :-) ).

> But how was I supposed to know that? It isn't stated anywhere! There
> is a faint tantalizing hint of conventional documentation (actual
> descriptive text) in the book, which implies that one would expect to
> see more of that, but there isn't any more. How about a FAQ entry
> to tell people "the C API is documented in the .h files; for other
> languages, read the SWIG documentation and the SWIG wrapper files to
> learn how the C API is transformed to those other languages". Then at
> least people would have a place to start.

Yes, that'd be a fine FAQ entry; you've written half of it already.
See http://subversion.tigris.org/mailing-list-guidelines.html#patches
for guidelines on how to submit a patch (including a patch to the FAQ,
not just to source code). The master copy of the FAQ is here:
http://svn.collab.net/repos/svn/trunk/www/faq.html

> Daniel> I've written very complex applications using the SWIG API,
> Daniel> that use parts of SVN i was never familiar with at all (IE
> Daniel> the fact that i am an svn developer didn't help me), and it
> Daniel> just wasn't that big a problem.
>
> Hm. Well, part of the trouble I have is that I was trying to do
> something quite simple, which I could have done in a shell script in
> 15 minutes (but not robust enough to my taste). And it took several
> hours of Brownian motion, doing random experiments that lead nowhere.
> I just don't find this acceptable... sorry.

Then don't accept it -- do something about it!

Thank you,
-Karl

-- 
www.collab.net  <>  CollabNet  |  Distributed Development On Demand
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Received on Mon Mar 13 06:51:47 2006

This is an archived mail posted to the Subversion Users mailing list.