[Flac-dev] FLAC docs (was: Is FLAC fully cooked for OS X yet?)

[Josh Coalson]

--- Evan Olcott <ev at audiofile-engineering.com> wrote:
> 
> On Jan 2, 2007, at 1:56 PM, Josh Coalson wrote:
> 
> >> OK, so I've been trying for a day now to get FLAC implementation
> in
> >> our apps. Suffice it to say that due to the "interesting"
> >> documentation [...]
> >
> > could you elaborate?
> 
> Well, I've just never seen anything like it before. There's a step- 
> through, to be sure, but I got more information out of the headers  
> than the actual online stuff, which seemed very intra-linked, very,  
> shall we say - generated automatically...
> 
> I'm used to Apple's documentation, which is very clean and clear.  
> This seemed a little overkill - lists of functions, lists of headers,
>  
> lists of classes, alphabetically (even though 99% of them all start  
> with FLAC__), etc. It seemed a little "too much" where it looks like 
> 
> it could  be a lot simpler - the API isn't really as complex as it  
> looks like at first glance...

yes, the API docs are generated from headers by doxygen, and I
personally don't find a lot of the sections on the top navbar useful
except as an index... BUT it does have quite a lot of human-written
text in it.  (libFLAC is ~40% comments by weight which is unusually
high.)  it's best to start right at the top
http://flac.sourceforge.net/api/
and move down into the detailed modules, e.g.
http://flac.sourceforge.net/api/modules.html ->
http://flac.sourceforge.net/api/group__flac__decoder.html ->
http://flac.sourceforge.net/api/group__flac__stream__decoder.html

can you point to some apple docs which you like?  a lot of the
things I tried to find out about (like quicktime) either had
obsolete or inadequate info (but they were human-written) or
javadoc shells.  I hear from other developers that their docs
in the old days were much better.

if you're talking about the interconnectedness of the non-API
stuff (starting at http://flac.sourceforge.net/documentation.html)
it used to be more of a straight-through read, which I prefer too,
but the feedback I get is that most people want a more direct
route to solving their specific problem, so I reorganized it that
way.

Josh


__________________________________________________
Do You Yahoo!?
Tired of spam?  Yahoo! Mail has the best spam protection around 
http://mail.yahoo.com