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.
Hi Luke,
I agree that SYNOPSIS and DESCRIPTION sections are really important and I would not want them to be lost - maybe these should be a requirement for uploading to CPAN6?
I seldom program in Java too :-) But one of the few things I liked about Javadoc is the ability to traverse the interfaces of classes quickly - and this is tied to hypertext.
Forget I used the J word --- what I'd like to see in the documentation system is the ability to quickly browse and traverse the linkages between modules and 'things'.
The documentation requirements for Perl6 are a step up from Perl5.
Perl6 programs will have 'backlinks' and relationships with a number of things: rules, grammars, classes, methods, roles, subs and traits etc. These in turn may have their own hierarchies. The structural aspects of the contract of a Perl6 class needs to be prominently and uniformly communicated.
I think we need a hypertext browsing capability so that we can jump around the distilled contract of a class: both our own modules and each other's.
In this way you could traverse the interlinkages between ALL things on CPAN6: "What grammar inherits from that? What modules use this grammar? What classes do this role? What programs test this class? What grammars inherit from this grammar?"
I'm not advocating terse documentation - but I would like to add to the wishlist:
* universal consistent hypertext code browsing both locally and on ~~ /CPAN6/.
Nige
