| 1 |
On Thu, 25 Nov 2004, Georgi Georgiev wrote: |
| 2 |
|
| 3 |
> maillog: 24/11/2004-21:10:14(+0100): Benjamin Schindler types |
| 4 |
>> I've got to throw an idea in here.... How about a doxygen-style |
| 5 |
>> documentation? No, it doesn't have to be doxygen, but I'm thinking of |
| 6 |
>> this idea. Instead of looking at every eclass, why not have some |
| 7 |
>> standard-format documentation in an eclass itself and let a tool create |
| 8 |
>> the documentation in whichever format he wishes to do so. |
| 9 |
>> Just my 2 cents... |
| 10 |
> |
| 11 |
> Yep, was about to propose something based on perl's POD, but realized it |
| 12 |
> might be a little ugly to keep a large section of comment-ed out to-be |
| 13 |
> documentation in the eclass itself. |
| 14 |
> |
| 15 |
> Or are you having something different in mind? |
| 16 |
|
| 17 |
If you really think that in-line docs are ugly, use vim(1), and |
| 18 |
automagically fold them out of your view (:help foldexpr, although this |
| 19 |
can be set to happen in the eclass syntax file). I suspect that most of |
| 20 |
the people who only occasionally work with the eclasses, and those who |
| 21 |
are just starting to use the eclasses, would find them more useful than |
| 22 |
ugly. |
| 23 |
|
| 24 |
Putting the documentation in-line makes it more convinient, so as to |
| 25 |
lessen the excuse of, 'Well, I was going to update the docs after I knew |
| 26 |
it worked, but I got distracted.' Personally, I find it useful to |
| 27 |
change the in-line documentation before I change the code; this way, if |
| 28 |
I get distracted, any of the developers that share my development box |
| 29 |
can see where I was going, including me six months later. (This happens |
| 30 |
far more often than I'd like.) It can also help to focus ones ideas |
| 31 |
before one starts coding. |
| 32 |
|
| 33 |
Ed |
| 34 |
|
| 35 |
-- |
| 36 |
gentoo-dev@g.o mailing list |
Archives