* 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. Overmeer MARKOV Solutions
[EMAIL PROTECTED] [EMAIL PROTECTED]
http://Mark.Overmeer.net http://solutions.overmeer.net
