Re: API documentation wanted (for Python in particular)

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

>> 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.

 Daniel> Okay, well, you can always use the doxygen generated docs if
 Daniel> you like.

 Daniel> That is how gcc, for example, documents libstdc++.

 Daniel> It's pretty standard in projects i've seen to keep API
 Daniel> documentation in the code, or have it generated from the
 Daniel> comments. Anything else gets out of date *very* quickly, and
 Daniel> becomes worse than useless.

I'd offer gccint as a counterexample. I suppose it's a fairly rare
one; other *int manuals tend to be marginal at best.

Part of the problem is this: the .h files or doxygen provide the
"vocabulary" but nothing else. There is no description of the
organizing principles, or of the semantics. What is a "baton"? How
are log messages handled? Etc...

I feel a bit like a guy trying to learn German and being offered a
dictionary as the answer. Oh yes, and it's a German-Russian
dictionary, and I don't know Russian. "No problem, there's a Russian
textbook over there". Yes, but even once I learn the words of German
that doesn't mean I know German.

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