Front page | perl.perl6.language |
Postings from June 2007
Re: documentation standards (was "[svn:perl6-synopsis] r14421 -doc/trunk/design/syn")
Thread Previous
|
Thread Next
From:
David Green
Date:
June 21, 2007 17:33
Subject:
Re: documentation standards (was "[svn:perl6-synopsis] r14421 -doc/trunk/design/syn")
Message ID:
a0623090fc2a0a993187e@[172.27.1.7]
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
Thread Previous
|
Thread Next