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.


Reply via email to