Re: [Chicken-users] egg documentation

[Peter Bex]

On Tue, Feb 12, 2008 at 03:16:35PM -0200, Mario Domenech Goulart wrote:
> Hi Mark,
> 
> On Tue, 12 Feb 2008 10:52:02 -0600 "Mark Fredrickson" <address@hidden> wrote:
> 
> > This idea dove tails with discussion last week of providing docstrings
> > for lambdas. Felix pointed out that there is a hook to capture lambda
> > documentation. Will this work for documenting eggs, which might also
> > have data types, parameters, other info?
> 
> I'm not sure if that's a good way to provide full documentation for
> eggs and chicken.

I don't think so either.

> One of the problems I see is that there are other types of objects
> besides 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?

Another thing is that docstrings are even less semantically rich than
the wiki.  They're just plain text, no way to hyperref ('see also'),
no way to refer to arguments/function names etc.

If you have semantically rich content you could do really cool stuff
like making a context-sensitive help like you see in some modern IDEs
for other languages etc.

> The full documentation for eggs and chicken itself is more than the
> documentation of procedures and other objects.  There are examples,
> authors, license sections etc, which are not source code.

Yep, that too.

> I'm afraid merging two sources of documentation (from source code
> files and, I guess, manually written doc files) can lead to confusion
> and "kludgeness".

I'm afraid of that too.

Cheers,
Peter
-- 
http://sjamaan.ath.cx
--
"The process of preparing programs for a digital computer
 is especially attractive, not only because it can be economically
 and scientifically rewarding, but also because it can be an aesthetic
 experience much like composing poetry or music."
                                                        -- Donald Knuth

pgpauexIvqmiN.pgp
Description: PGP signature