Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)

[Nigel Hamilton]

> 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