Stevan Little writes: > Introspection is nice, but I disagree that documentation should be that > transparent. One of the nice things I have found about perl and CPAN in > particular is that many people tend to document their modules very > well. Which not only includes information about method/function > signatures, but also contains both example code and actual "written" > documentation. The mini-articles many people write for the DESCRIPTION > section can sometimes be much more informative than their individual > method/function docs.
I agree. I think the biggest mistake Perl 6's documentation system could make is to make it Javadoc-style automatic. This is one of those weird, backwards, cultural decisions, where we actually want to make the programmer's life a little harder. When I (seldomly) progam in Java, I find it very hard to use any libraries, because all the libraries have good method-level documentation, but none of them has good interface (conceptual, not C<interface>)-level documentation. I basically have to understand how the library author organized his code in order to use his library. On the other hand, Perl has this wonderful module idiom of SYNOPSIS and DESCRIPTION. SYNOPSIS generally shows you how a very small program would use the library (the thing Java libraries are missing), and DESCRIPTION goes in detail about the things you need to know. The things you don't need to know you can get by reading the code. If you give people Javadoc-style documentation, they can feel like they've documented their module that way, and feel that it's not necessary to do any more. I probably would. Luke
