[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: Paul Koning <pkoning_at_equallogic.com>
Date: 2006-03-13 02:01:53 CET

>>>>> "Daniel" == Daniel Berlin <dberlin@dberlin.org> writes:

>> Expecting people to read cryptic .h files AND even more cryptic
>> SWIG files is really not very nice at all.
 Daniel> See, this is where i disagree. Expecting people to read well
 Daniel> documented .h files to discover what the interface for
 Daniel> something is, IMHO, is perfectly fine.

 Daniel> Expecting people to understand that in order to wrap this API
 Daniel> into certain languages, some mechcanical transformations were
 Daniel> performed to it, is also okay.

 Daniel> You are acting like this is a huge secret deal where every
 Daniel> single function has had something different done to it, and
 Daniel> it's just not so.

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.

Personally, I don't find that "read the source" is reasonable
documentation, but I guess opinions differ. And I suppose SWIG is a
mechanical transformation.

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.

 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.

      paul

---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Received on Mon Mar 13 02:02:38 2006

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