On Sun, 2006-03-12 at 20:01 -0500, Paul Koning wrote:
> >>>>> "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.
Okay, well, you can always use the doxygen generated docs if you like.
That is how gcc, for example, documents libstdc++.
It's pretty standard in projects i've seen to keep API documentation in
the code, or have it generated from the comments. Anything else gets
out of date *very* quickly, and becomes worse than useless.
>
> 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.
It is true that nobody has yet written this stuff. Documentation in
open source projects is one of the things people work on the least,
unless someone is paid to do it. This is generally true of non-open
source projects i've observed as well :).
The best way to get good docs is to write down what you've discovered,
or learned, and put it somewhere, and someone will come and improve it
with what they've learned, etc.
---------------------------------------------------------------------
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:11:41 2006