Re: documentation standards (was "[svn:perl6-synopsis] r14421 - doc/trunk/design/syn") On 6/21/07, Smylers wrote:
>Mark Overmeer writes:
>  > The boundary between freedom and anacharchy is faint.
>Indeed.  And I'd much rather we err on the side of anarchy.

I'd much rather we didn't err at all!  Just because something isn't 
"perfect" doesn't mean it's an error, or that it's not worth trying.

>[...] and inadvertently prevent somebody in the future from doing 
>something really clever that none of us have yet thought of.

How does having some standards prevent anybody from doing anything? 
Nobody's proposing Perl Documentation Police who will come and 
kneecap you if you try to do something new and better.

>  > And those have a good example in standard UNIX manual-pages.  So:
>>  there is a definitions for them, which most people have seen.
>I am sceptical of your claim that most Cpan authors have seen any 
>official definitions of sections in Unix manual pages.

He only said they'd seen good examples.  Which, really, are a kind of 
standard.  Even if all we did was to write down those standards 
somewhere so that people weren't required to absorb them by osmosis, 
that would be a good thing.

>I agree.  And programming languages develop in hard-to-predict ways, 
>which is why Larry is putting lots of flexibility for things to be 
>redefined into Perl 6, so it can grow and adapt in line with future 
>developments.  It would be good if Pod can keep up.

Great, so let's have lots of rules and standards for documentation -- 
we'll just make sure they include formal ways to accommodate future 
growth.  Perl 6 is full of rules (it's software! all it is is a big 
list of rules!), but it's still wonderfully flexible.  I want lots of 
doc-rules, but absolutely do I want them to be flexible too.

>I just don't believe that _anybody_ can come up with rules that 
>won't be bettered at some point in the future.

Maybe; that doesn't mean we can't start off with some "really good" 
rules today.  Besides, insofar as that's true today, it will be just 
as true in the future, so we'd be perpetually waiting for tomorrow's 
Better Rules instead of actually doing something with today's Pretty 
Good Rules.

>I've encountered Javadoc, and I really dislike it[*0].  The fact 
>that a standard exists does not make it a good one.

Nope.  But we're living in Javadoc's future, so let's learn from its 
limitations and make P6doc better.

>[...]
>       Exceptions: none
>       Side Effects: none
>
>Lots of structure and consistency, but in practical terms no 
>additional information compared to my informal doc -- and the 
>verbosity and repetition actually make it harder to spot the 
>information you want.

Well, clutter like "Blah: none" seems to me to be more the fault of 
the doc-formatter for not hiding lines like that.  But even though I 
naturally tend to the lazy side myself, you have to admit there is 
*some* info gained by requiring the "Blah: none" -- namely that there 
really is no blah (as opposed to, "There might be, but I forgot to 
say so.").

That makes me think of a practical example, though:  Say you want to 
find all the functions in your code that do have side-effects.  Being 
able to search for code that has an explicit "side-effects" tag with 
a standard value of "none" (or undef or whatever) would be really 
useful.

Actually, can't P6 tell whether code has side-effects or not?  Which 
is still a case for having structured docs; Perl could parse your 
code and automatically insert a properly-formatted line to say so, 
competently situated in the right place inside the rest of the 
documentation you had to write manually.  (And your local "style 
sheet" could determine whether you see that line only when there are 
side-effects, or only when there aren't, or never, or....)

The point isn't to have *only one* way to document your code; it's to 
have *at least one*, that is, at least one way to build the FAD 
(Fancy Advanced Documentation) tools of the future.  I envision 
things like "perldoc Test::BigHugeModule --sub=is" (sure beats 
searching the page with ctrl-F "is"; and a pretty modest wish, I 
think).  Or perhaps I'm in the debugger, looking at the value of $foo 
and wondering why it ==666 and whether that's a bad thing -- I could 
hit a key and display the docs for that arg.  Or I type "bar(" and my 
text editor helpfully notices that I'm using the bar() function, asks 
Perl for the specs, and pops up a handy summary of each parameter; it 
could even see that bar() takes exactly one argument, of type 
Mammal::African, and that I have exactly one such variable in scope, 
$aardvark, and be ready to auto-complete it for me.

Actually, that last bit about detecting types in a signature or 
variable is already possible, because Perl has formal rules for 
specifying such things in your code; I'd like the same advantages 
conferred on the documentation as well.
If you have a file with the text of the Magna Carta, a computer is 
not going to understand it.  You can add a bit of structure, like 
headings and numbered lists, but we're a long way from software that 
can interpret mediaeval politics.  We do, however, have computers 
that can interpret [and even compile =)] Perl... it has subs and 
classes and lexicals and globals (and comments, and POD!).  What a 
shame it would be if all that structure and information that is 
already available could not be put to good use by documentation tools.


Anyway, in case I'm sounding too polarised I should acknowledge that 
I do agree with your underlying points about not overly restricting 
things.  I want rules *and* flexibility, and I believe we can have 
both, just as Perl itself is very structured (more so than P5), but 
is at the same time extremely flexible (also more so than P5!).  I do 
agree that docs should have as much freedom as code; I want them to 
have as much structure too.


-David

