[FM Discuss] Documenting internals versus use (was: Beautiful Documentation with Sphinx)

[adam hyde]

so far we have dodged the API bullet, janet took a few though and she
looked a little rattled ;)

im really not sure what we should do about this. as Anne said recently,
we are offering a toolset...so if someone comes along and says...i want
to doc my api...what do we do? i think we say ok

any thoughts?

adam




On Wed, 2009-03-11 at 12:10 -0400, Andy Oram wrote:
> I'd like to take the discussion of Sphinx, etc. up a notch. Is it part of FM's mission to help developers document their code? That's basically an issue of internals. I suppose some of these javadoc-type of comments are also useful for API documentation, but I suspect that serious API documentation must be generated with a more comprehensive, high-level view of the API.
> 
> The idea of embedding comments in each function goes back to Knuth's WEB, which never went anywhere but seems to be reinvented with every new generation of programmers and every language.
> 
> Andy
> _______________________________________________
> Discuss mailing list
> Discuss at lists.flossmanuals.net
> http://lists.flossmanuals.net/listinfo.cgi/discuss-flossmanuals.net
-- 
Adam Hyde
Founder FLOSS Manuals
German mobile : + 49 15 2230 54563
Email : adam at flossmanuals.net
irc: irc.freenode.net #flossmanuals

"Free manuals for free software"
http://www.flossmanuals.net/about