Re: [Chicken-users] Re: dbus:send bug

[Peter Bex]

On Thu, Mar 17, 2011 at 09:17:13AM -0400, John Gabriele wrote:
> > You can also make the argument that you're being distracted by the way
> > the code is laid out.  If you are documenting completely separately,
> > you can think about the flow of text that makes most sense, grouping
> > procedures that fit together logically. {snip}
> 
> A system that I think works pretty well is:
> 
>  1. separate standalone docs for things like overview, tutorial,
> cheatsheet, cookbook
>  2. API docs in the source code file (easily extracted), though, all
> placed together at the end
>  3. comments for low-level explanations of why something is done a certain way

That means three times the amount of work for the programmer.  And in
practice, that means 1 and 3 are not going to be done.  Like I said,
automatically generated "documentation" is often used as an excuse by
the lazy not to do proper documentation.

It also means more work and headaches for the maintainers of the Chicken
infrastructure to accomodate for all these new fancy ways of doing
documentation, and more explaining to users why their docs are so
fragmented.

So unless you're willing to draft up a full proposal on how this will
integrate in our infrastructure and write all the required code, I
suggest we stop this pointless discussion.  We're already having a
similar, equally pointless, discussion on the other list :(

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