Re: [Chicken-users] egg documentation

[Shawn Rutledge]

On Feb 12, 2008 11:21 AM, Peter Bex <address@hidden> wrote:
> > One of the problems I see is that there are other types of objects
> > besides lambdas.

Everything should be able to have documentation comments (by which I
mean S-exprs), not just lambdas.

> Another problem is that docstrings are very limited in what you can put
> in them.  If you cram a tutorial in them, the source becomes unreadable
> and if you keep it brief, where do you put the other docs?

What's wrong with having longer docs be separate?  What about coming
up with a consensus on a path where such docs will be stored, so that
within the documentation comments (which are part of the code) it's
possible to make links to stuff like that? e.g. (see (href
"eggs/myegg/tutorial")) would be analogous to a Doxygen @see
directive.  When the doc comments (s-exprs) are parsed and the real
documentation is generated (HTML and whatever other forms) the links
can be translated to full paths or relative paths, whatever works.
And installing an egg should install the real documentation to a known
path like /usr/share/doc/chicken/eggs/myegg.  If all the documentation
were in one place like that, we would not be needing to use the online
documentation so much, and it would be possible to work without a
network connection sometimes.  (No doubt the bandwidth on callcc.org
is much higher than it needs to be, just because of the lack of this.)
 A local index should be built too, or a local full-text search engine
could be used, so that the search feature of the wiki is also
replicated on every Chicken installation.  Until we get around to that
part, it would at least be possible to make do with whatever your
usual local search engine is (Beagle, hyperestraier, swish++,
mnogosearch etc.)  Linux machines often have Apache configured so that
http://localhost/doc goes to /usr/share/doc anyway.  Some of them have
search engines set up for local documentation already, too.