On Sat, Feb 22, 2003 at 10:41:12PM +0100, Stefan Westerfeld wrote:
>    Hi!
> 
> On Fri, Feb 21, 2003 at 10:22:27AM -0700, David Bishop wrote:
> > *obligatory complaint*
> > Um, the docs on arts really suck :-(  Maybe I'm just spoiled with the great Qt 
> > and KDE docs, but it's really disappointing to find that even the headers are 
> > poorly commented (for instance, see Arts::Refiller at 
> > http://www.arts-project.org/doc/headers/Arts__Refiller.html, and based soley 
> > off of that (or anything else on that site), tell me what it's return value 
> > is supposed to represent, or what, exactly, is supposed to be in buffer after 
> > it returns.  I'm having to figure this stuff out by reading the source to 
> > other PlayObjects :-((  (thanks for the pointers to those, by the way.  the 
> > corrollary to the "docs suck" complaint would be that the mailing list is 
> > responsive)
> > *end of obligatory complaint*
> 
> Free Software: if it breaks, you get to keep both pieces. Please, if you
> find something thats wrong, learn not to accept it. Send me patches to
> documentation if its broken. Offer to work on the website if its insufficient.

First: that's probably my favorite quote regarding free software.  I
keep thinking about getting it on a bumper sticker...

Second: I am :-)  My first two projects are two more fully comment the
headers and create some "dummy" projects.  I don't think I'm the only
one out there that learns best by seeing how other people do things, and
small, well-commented examples go along way to getting there.

> TrollTech has a lot of full time employees only working on Qt, and getting
> paid for that. They do have customers. Thus its sure that they do have the
> resources to write good code and really good documentation.

That's very understandable, but I also mentioned KDE (i.e., libs and
base).  :-)  While there are parts of the KDE docs that aren't shining 
examples of completeness either, they tend to be much better than what
I've seen so far for arts. BUT, I don't say that as disrespect, or to
say that you "haven't done enough" (whatever that's supposed to mean in
a free-software context), just a (sad) statement of fact.  I think it
was you that said (a few threads up) that we have to discuss weaknesses
as well as strengths, and as a budding developer, lack of/poor quality
docs is arts's biggest failing.  I firmly believe that arts latency is
"good enough" for the vast, vast majority of users out there, and that
throwing out source-code compatability (or at least staying close) would
be a mistake.  But unless I'm willing to back up my opinion with code, I
don't see as how it matters all too much what I think...

Expect the first few patches against headers in the upcoming week.

D.A.Bishop
_______________________________________________
kde-multimedia mailing list
kde-multimedia@mail.kde.org
http://mail.kde.org/mailman/listinfo/kde-multimedia