Re: Progressively Overhauling Documentation
Mark Overmeer [EMAIL PROTECTED] writes:
Oops, someone starts the holy war (again). Wether you put the docs
in begin or end of the file, or intermixed with the code has a lot
to do with your personal background.
Sorry for the late reply, but I can't let this stand without further
elaboration: intermixing the POD with the functions is something some
of us would really like to do, but in Perl5 the evil stupid whitespace
rules of POD make it impracticable, because it horks over the
indentation (and thus the legibility) of the whole program.
If we fix nothing else about POD in Perl6, it is *imperative* that it
become possible to indent the POD to at least the same level as the
code. Otherwise POD will never become a viable substitute for the
extensive comment blocks it ought to displace.
--
$;=sub{$/};@;=map{my($a,$b)=($_,$;);$;=sub{$a.$b-()}}
split//,[EMAIL PROTECTED]/ --;$\=$ ;- ();print$/
Re: Progressively Overhauling Documentation
* Juerd ([EMAIL PROTECTED]) [040823 19:46]:
David Green skribis 2004-08-23 11:30 (-0600):
One of the selling features (or one of the features that is always sold)
of POD is that you can mix it with your code. Except nobody does, at
least I can't recall that last time I saw a module that did that, and I
don't think I've ever really done that myself. The POD usually sits in
a lump at the end of the file.
Oops, someone starts the holy war (again). Wether you put the docs in
begin or end of the file, or intermixed with the code has a lot to do
with your personal background.
I also think POD should be overhauled completely. I've been thinking
about proposing something like:
sub foo (
) description {
Calculates the foo-intersection of $bar and $xyzzy, optionally
blah blah blah...
} returns Array | undef {
# real code here
}
I found a few suggestions on the list, but... it's oversimplifying
things. Let's state
1) Code is doing things
2) Documentation explains how to use the code (some people explain
the code itself, but that is where the '#' comments are for)
To be able to write code easily, it should be compact enough to get a
good overview. Intermixing code and comment is a bad idea. For
instance in my programs, docs are about 5 times the volume of the
code which would be ugly in the proposed solution.
I prefer to put documentation just before the code. That's the only
way my sloppy mind can preoduce docs which stay in sync with the
intention of the code.
Certainly in larger programs --and always in OO programs-- the
functions methods in a user's document can be organized better
than the order of the code. So: why not support that? What do you
need to be able to do that?
In my case, I had to document my set of distributions. It's 125
packages on the moment, all in OO with up to 4 levels of hierarchy.
In total 988 methods, 174 diagnics explained (errors and warnings)
and 242 examples included. Do you think that you can document
this in POD?
The thing which POD lacks the most, is that it is visual markup
(like B and I in HTML) not logical markup (like STRONG and EM).
So, I added logical markup markers, like =method =overload =function.
Then, =error and =warning clears that up, and =example starts some
docs. =option, =default, =requires describe the OPTIONS
A full method in my code looks like this:
=method showSomeText TEXT, FORMAT, OPTIONS
Print the TEXT in the specified FORMAT.
=option linewidth INTEGER
=default linewidth 70
The maximum number of characters.
=requires language STRING
ISO indication of the languages
=example
$obj-showSomeText('hoi!', '%s', language = 'nl')
=error language required
The language is not use on the moment, but still must be
specified.
=cut
sub showSomeText
{ my ($self, $text, $format, %option) = @_;
my $lw = $option{linewidth} || 70;
my $lang = $option{language} or die language required;
printf $format, $text;
}
The number of options tend to grow when the program gets bigger.
Especially the constructors (like new()) can have many. On some
levels of hierarchy you may want to add new options, or change
their default, or fixate it.
OODoc is the module which processes the MANIFEST file of one or more
modules to produce real documentation out of this. POD is a
simplification, but there is also enough info to produce real HTML
(which optimal hyperlinks). With HTML, you can create templates to
organize the info in the pages (the OODoc distribution come with
examples for very small and for a huge setup).
The documentation fragments are split, joined, grouped, sorted,
formatted and reformatted in various ways to produce the optimal
result for users of the module.
As example, the HTML output for MailBox (and related):
http://perl.overmeer.net/mailbox/html/
Hey! Before you say anything: it is very difficult to give any
form of documentation on close to 1000 methods! Verbosity on
various spots is configurable in the templates.
TO MAKE MY POINT
I do not want to turn people over into using OODoc, that's not the point.
But I would really like Perl6 to have a logical markup (which may or may
not have code syntax, like description{} introduced above).
We (I) need more than only a discription of some options and the method
as a whole. Let's try to get an integrated solution, including the
defaults, diagnistics, and examples.
IMO, user documentation should stay outside the main part of the code
or discription, to keep the code readible.
Any nice solutions for Perl6?
--
MarkOv
drs Mark A.C.J. OvermeerMARKOV Solutions
[EMAIL PROTECTED] [EMAIL PROTECTED]
http://Mark.Overmeer.net http://solutions.overmeer.net
Re: Progressively Overhauling Documentation
David Green wrote: In [EMAIL PROTECTED], [EMAIL PROTECTED] (Aaron Sherman) wrote: This bit of POD made me think about POD's lack of tabular formatting, a common idiom in technical documentation. I know POD is still in the wings, as it were, but I wanted to say this before I forget /me flings coffee cup against the wall [no, not Larry!]. Has anyone seen Natural Docs? http://www.naturaldocs.org/ Clayton
Re: Progressively Overhauling Documentation
David Green skribis 2004-08-23 11:30 (-0600):
One of the selling features (or one of the features that is always sold)
of POD is that you can mix it with your code. Except nobody does, at
least I can't recall that last time I saw a module that did that, and I
don't think I've ever really done that myself. The POD usually sits in
a lump at the end of the file.
I'll consider inline documentation when POD can be inlined. But as long
as =command paragraphs need to start in the first column, I'm not
interested in this feature.
Having a nice, compact way to declare sub signatures is good. Being
able to document those signatures, not just nearby, but
*simultaneously*, would be great.
IMHO, with Perl 6's verbose signatures, it'd really help if POD could
copy the signature literally. This is one small thing I do like about
PHP documentation.
I also think POD should be overhauled completely. I've been thinking
about proposing something like:
sub foo (
Foo::Bar$bar,
Quux::Xyzzy $xyzzy,
+$verbose,
+$foo
) description {
Calculates the foo-intersection of $bar and $xyzzy, optionally
blah blah blah...
} returns Array | undef {
# real code here
}
which would get rendered as:
foo (Foo::Bar $bar, Quux::Xyzzy $xyzzy, +$verbose, +$foo)
returns Array | undef;
Calculate the foo-intersection of $bar and $xyzzy, optionally
blah blah blah...
Having {} instead of would also please me. Especially if we can get
{b:foo} instead of Bfoo.
But I haven't really given this much thought. That's why I haven't
proposed it yet. But since POD is a hot topic now anyway, let's see what
everyone thinks about this.
Juerd
Re: Progressively Overhauling Documentation
Juerd wrote:
David Green skribis 2004-08-23 11:30 (-0600):
One of the selling features (or one of the features that is always sold)
of POD is that you can mix it with your code. Except nobody does, at
least I can't recall that last time I saw a module that did that, and I
don't think I've ever really done that myself. The POD usually sits in
a lump at the end of the file.
I'll consider inline documentation when POD can be inlined. But as long
as =command paragraphs need to start in the first column, I'm not
interested in this feature.
What if we add Cdoc attribute that the execution compiler would
discard, but POD compilers (and debuggers) could make use of? I believe
that would even allow a particularly stringent corporate policy to
create a flavor of 'strict' which required documentation of various
classes of elements (though whether anyone would work there is another
question...).
But imagine debugging code, and being able to quickly see a comment on a
variable you can't figure out.
Juerd's sample would become:
sub foo :doc(take an Foo::Bar, and foo it over.) (
Foo::Bar$bar:doc(what to foo up.),
Quux::Xyzzy $xyzzy :doc(Xyzzy to foo bar with),
+$verbose,
+$foo
} returns Array | undef {
# real code here
}
-- Rod Adams
Re: Progressively Overhauling Documentation
Rod Adams skribis 2004-08-23 13:16 (-0500):
sub foo :doc(take an Foo::Bar, and foo it over.) (
Anything involving a string is not good for documentation, because in
documenation it must be *easy* to add code examples. Besides that, ()
would make me want to put it all on one line, and that may be a little
*too* concise for documentation.
class Dog {
sub bite (
Int $strength is validated { 0 $_ = 9 } # Do we have
# something like this
# yet?
) description {
foo bar baz, demonstrated here:
=verbatim {
...
}
In any case, {b:CAVE CANEM}. # Translated: beware of the dog.
# And yes, that's a comment in POD, and should not be rendered.
} {
.mouth.open;
.head.extend;
.mouth.close $strength;
}
}
Juerd
RE: Progressively Overhauling Documentation
unsubscribe
-Original Message-
From: Juerd [mailto:[EMAIL PROTECTED]
Sent: Monday, August 23, 2004 12:01 PM
To: Rod Adams
Cc: [EMAIL PROTECTED]
Subject: Re: Progressively Overhauling Documentation
Rod Adams skribis 2004-08-23 13:16 (-0500):
sub foo :doc(take an Foo::Bar, and foo it over.) (
Anything involving a string is not good for documentation, because in
documenation it must be *easy* to add code examples. Besides that, ()
would make me want to put it all on one line, and that may be a little
*too* concise for documentation.
class Dog {
sub bite (
Int $strength is validated { 0 $_ = 9 } # Do we have
# something like this
# yet?
) description {
foo bar baz, demonstrated here:
=verbatim {
...
}
In any case, {b:CAVE CANEM}. # Translated: beware of the dog.
# And yes, that's a comment in POD, and should not be rendered.
} {
.mouth.open;
.head.extend;
.mouth.close $strength;
}
}
Juerd
Re: Progressively Overhauling Documentation
Thalhammer, Jeffrey BGI SF skribis 2004-08-23 12:03 (-0700): unsubscribe It doesn't work that way. If I'm not mistaken, unsubscribing is done by sending mail to [EMAIL PROTECTED]. Also, you might want to consider using a sane e-mail program and some training in quoting :) Juerd
Re: Progressively Overhauling Documentation
At Mon, 23 Aug 2004 19:46:34 +0200,
[EMAIL PROTECTED] (Juerd) wrote:
I also think POD should be overhauled completely. I've been thinking
about proposing something like:
sub foo (
Foo::Bar$bar,
Quux::Xyzzy $xyzzy,
+$verbose,
+$foo
) description {
Calculates the foo-intersection of $bar and $xyzzy, optionally
blah blah blah...
} returns Array | undef {
# real code here
}
which would get rendered as:
foo (Foo::Bar $bar, Quux::Xyzzy $xyzzy, +$verbose, +$foo)
returns Array | undef;
Calculate the foo-intersection of $bar and $xyzzy, optionally
blah blah blah...
I also think something like this is a great idea -- I've been doing a
lot of programming in Octave and Emacs Lisp, and the latter's
generated documentation makes it possible to program what would
otherwise be a completely baroque and unmanageable system. But I
wouldn't go for the syntax you have above. Why not just do it with a
property, then ship with a doc-generator that makes use of it?
sub foo($x is rw, $y) is doc .
Does some stuff, then frobs $x without mercy.
.
{
# ...
}
/s
Re: Progressively Overhauling Documentation
OK, there's one non-incremental idea: documentation that you can write in one place and display in some completely different order. (Shades of literate programming!) And although there are good reasons for keeping the docs in the same file as the code, there are equal but opposite reasons to keep it separate (if it's all piled up at the end of the file anyway). What gets presented to the user as one page could be bits and pieces from all over the place. Literate Programming handles reordering by allowing you to specify a hirearchical number as part of each doc piece. This could be easily a dded to POD. Something like: =(1.2.1) begin ... just default any unspecified values to incrementing the last one. A simple POD processor could just ignore them and a fancy one could use them to reorder the section accordingly. -- Mark Biggar [EMAIL PROTECTED]
Re: Progressively Overhauling Documentation
On Mon, 23 Aug 2004 [EMAIL PROTECTED] wrote: OK, there's one non-incremental idea: documentation that you can write in one place and display in some completely different order. (Shades of literate programming!) And although there are good reasons for keeping the docs in the same file as the code, there are equal but opposite reasons to keep it separate (if it's all piled up at the end of the file anyway). What gets presented to the user as one page could be bits and pieces from all over the place. Literate Programming handles reordering by allowing you to specify a hirearchical number as part of each doc piece. I am not sure I understand *why* you need reordering of documentation. Literate programming is useful because it reorders *code* while writing documentation in the intended order. Could somebody provide a concrete example of the need to reorder documentation? I was extensively using literate programming for the project I am working on. But after a while (7000 lines of p5 code, about 50 files) the cost of maintaining it seemed more than the gain even though I was heavily preprocessing the code to take the drudgery out, and I have come back to good ol' POD. I have come to believe that for short nasty pieces of code (implementing complicated algorithms) LP is a fantastic idea, but for larger systems that are not exactly imperative and have weird control flow (with hooks and such; or with an event loop of Tk), LP is no advantage. IMHO, for the few people who'd want to use LP, it would be easier and lazier to hack something like noweb to understand your annotations (perchance even understand POD :) ) than to make POD jump through hoops. --abhijit
