Re: [gentoo-dev] Gentoo beeping at me!

[Ed Grimm <paranoid@gentoo.evolution.tgape.org>]

On Thu, 25 Nov 2004, Georgi Georgiev wrote:

> maillog: 24/11/2004-21:10:14(+0100): Benjamin Schindler types
>> I've got to throw an idea in here.... How about a doxygen-style
>> documentation? No, it doesn't have to be doxygen, but I'm thinking of
>> this idea. Instead of looking at every eclass, why not have some
>> standard-format documentation in an eclass itself and let a tool create
>> the documentation in whichever format he wishes to do so.
>> Just my 2 cents...
>
> Yep, was about to propose something based on perl's POD, but realized it
> might be a little ugly to keep a large section of comment-ed out to-be
> documentation in the eclass itself.
>
> Or are you having something different in mind?

If you really think that in-line docs are ugly, use vim(1), and
automagically fold them out of your view (:help foldexpr, although this
can be set to happen in the eclass syntax file).  I suspect that most of
the people who only occasionally work with the eclasses, and those who
are just starting to use the eclasses, would find them more useful than
ugly.

Putting the documentation in-line makes it more convinient, so as to
lessen the excuse of, 'Well, I was going to update the docs after I knew
it worked, but I got distracted.'  Personally, I find it useful to
change the in-line documentation before I change the code; this way, if
I get distracted, any of the developers that share my development box
can see where I was going, including me six months later.  (This happens
far more often than I'd like.)  It can also help to focus ones ideas
before one starts coding.

Ed

--
gentoo-dev@gentoo.org mailing list