This is the mail archive of the
kawa@sourceware.org
mailing list for the Kawa project.
Re: strange problem with jetty
On 02/12/11 23:57, John Smith wrote:
Does the bulk of the documentation come out of comments in the source or is maintaining the documentation mostly a parallel endeavour?
I think the stuff you navigate to using the links on the left of the
home page is generated from doc/kawa.texi (which is a parallel
endeavour) in the SVN source, the doc/Makefile.am shows how it is
generated. The generated stuff from the source code lives at
http://www.gnu.org/software/kawa/api/ - it would be quite cool to run a
script that updates the javadoc on every new commit.
Speaking as a newcomer I found the documentation comprehensive. If I were to make a comment about the organization I guess there could be a clearer distinction drawn between "guide" and "reference". I treat the index as the reference section and the left-hand-side menu as the guide. And although I'm new to Kawa and Scheme, given some tolerant support I could volunteer some effort at grunt-level in assisting with documentation tasks where requested.
I think the interface to the online documentation could be improved, the
content is pretty good, but I find it quite awkward to navigate
sometimes, a lack of cross-references for instance. Racket's
documentation interface is really nice: search, cross-references,
pointers to more detailed notes, etc. I suppose a better set of tools
for generating this infrastructure would be nice.
The source-level comments are a little scarce, too. I try to document
that level as I understand new things, but it's a challenge to make sure
you keep that documentation up-to-date after modifications. Quite
frankly, I don't know how Per finds the time to write all this code and
produce the amount of documentation he does, so I'm certainly not
suggesting the situation is down to a lack of effort!
Charlie.