develooper Front page | perl.perl6.language | Postings from March 2005

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

From:
Nigel Hamilton
Date:
March 15, 2005 09:59
Subject:
Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)
Message ID:
Pine.LNX.4.60.0503151028370.29760@m1.turbo10.com
> 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









nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About