Mark Overmeer wrote:
This is exactly the form of documentation you do *not* want the
user to write, for various reasons:
Well, I agree it is the form that "you" (singular, specific) do not want; but
I'm not sure it's bad for "you" (plural, generic) to write in all cases. ;-)
* The explicit naming of the class name in method and attribute
descriptions is in general a bad idea: by inheritance, you get
sub-classes which also provide this method. In the people's
mind (I mean "normal people", not our "perl guru"), this
requires continuous translations which distracts from the message.
A dedicated OO documentation tool could certainly do a better job in that
case, I heartily agree. I'm looking forward to using one.
* How do you see this syntactically work in combination with the
item list? At least the POD(5) needed that. I need a combined
example.
I'm not sure I understand what you're asking here. Can you describe the
example you'd like to see?
* Having aliases is pratical, for referencing. However, in this
latter example it is used to help the programmer to shoot himself
in the foot. If you allow people to say "class" each time they
mean "role", or "function" where it is "method", then on the long
run people will start making avoidable programming mistakes.
In the chosen approach, this abuse cannot be avoidable. But it
may be a wise not to promote it by using it as example.
A good point. I will remove the example.
* Using ambient back-references this way probably requires a
two-pass document generator. AFAIK this is not required for the
design of POD6 so far.
Actually a two-pass generator is already required for Pod. A second pass is
always necessary whenever there are any forward-targetted L<#local link>
formatting codes in a document.
* the A<(..)> syntax is nice, but has a few dangers. Serious
problems. Your examples are a bit brief. A little larger:
method eat(Food $meal) {...}
=for DESCRIPTION
The A<method>() method has the following argument list: A<(..)>
Now the method gets implemented:
method eat(Food $meal) {
if($manger.isFull) { $manger.clean }
}
=for DESCRIPTION
The A<method>() method has the following argument list: A<(..)>
Oops... now the argument list became (without warning)
"$manger.isFull" So, either you impose a strict doc order, forcing
people into "your style", or people have to use an alias everywhere,
bulking the file. More subtle examples of this problem can be
created, for instance when the method defines a return type
Sure. But this is true of any scheme that doesn't do full parsing of the
ambient source code. Which Pod isn't going to do (but which, of course, you
may well choose to do in another documentation mark-up layer built on top of Pod).
* In the manual-page of my sub-class, I want to refer to the
documentation of specific attributes and methods. How?
Can I also refer to elements in distributions which are not
mine, so where I cannot add X<> or such? For instance,
when I inherit from a core Perl class?
This is not possible, using this mechanism, due to the lexical scoping of the
aliases. An automatic documentation-generator tool (that produces Pod) is more
appropriate for this task.
* In my sub-class, I want to enlist automatically the methods
and attributes which are inherited. Automatically of course,
because I want to avoid mistakes. In case of multi-level
inheritance, some way I need to know and show where each is
defined. How?
An automatic documentation-generator tool is more appropriate for this task too.
For instance, if your look at IO::File in Perl5, it defines
some own method, but then simply says: see also IO::Handle
and IO::Seekable. IO::Handle says: see also perlfunc and
perlvar. The more extended your OO model is, (Perl6's
structure is probably much more extended), the more levels
of hierarchy you get. Are users able to understand this?
Are developers able to maintain manual interface description
lists without mistakes?
Is the shown syntax sufficient for tools to create it
automatically? As decided, of course without looking at
the perl code itself.
Of course not. Pod is static explicit documentation mark-up. That mark-up may
be generated by humans or by clever documentation-from-code tools. Those
clever tools are what you're looking for, and what I'm sure you will easily be
able to create, using the Pod 6 and Perl 6 parsers as foundations, and perhaps
the Pod syntax as a output format (targetting the wealth of Pod-to-Whatever
translators we will provide).
Your design goal of A<> is to avoid replication of code information,
in which you succeeded. Now your write
method eat(Food $meal) {...}
=for DESCRIPTION
The A<method>() method has the following argument list: A<(..)>
In stead of
method eat(Food $meal) {...}
=for DESCRIPTION
The eat() method has the following argument list: Food $meal.
What I would like is to get rid of the replication of that description
line as well, using back-end specific templates/style-sheets.
Sure. I fully and completely understand that. And you will definitely be able
to build a tool that does that.
What about:
=definition
method eat(Food $meal) {...}
=for DESCRIPTION
...
With only a slight modification that is already valid Pod:
=Definition
method eat(Food $meal) {...}
=for DESCRIPTION
...
(The user-specified block type has to be mixed case, and the block requires an
empty line after it otherwise the "method..." line will be Pod, not Perl code)
But with that slight change in syntax you could then use the standard Pod
parser to segment your document into mark-up and ambient code, search the
resulting object tree for 'Definition' nodes, grab the immediately following
ambient code block, parse it using Perl 6's own grammar, then autogenerate
content for the next 'DESCRIPTION' node in whatever form you would like it to
be, using information extracted from the parsed code.
Of course, you could just as easily do that without needing the '=Definition'
block at all, since you could simply look for 'DESCRIPTION' blocks in the
parsed Pod and then parse any definition from any preceding ambient block for
code.
Or, since the Perl 6 grammar can preserve Perl comments in the parse tree, you
could even create a tool that understood an abbreviated notation such as:
method eat(Food $meal) {...} #=Definition=#
=for DESCRIPTION
...
and which documented only Perl definitions that are followed immediately by a
comment in the appropriate special form.
The point is: the design of Pod allows you to use *any* of those alternatives.
It does that by providing a simple and extensible mark-up notation, an
efficient parser for that notation, and good integration with Perl itself, so
you can build whatever kind of documentation tools you find most useful.
And, no, I don't propose to "canonize" just one of those special ways of
auto-creating documentation by designing it into the core specification of
Perl 6/Pod 6. Instead, I intend to provide a simple, independent mechanism for
admixing code and static documentation, with a reliable and efficient parser
to separate them again. Then I propose to allow more experienced and cleverer
people (such as yourself) to develop powerful tools on top of those basic
mechanisms.
In other words, in designing Pod I'm attempting to create something at the
abstraction level of RTF or LaTeX or XHTML, not something analogous to MS Word
or Maple or HyperCard. That is: something that you can use directly for simple
tasks, and something you can also build tools on top of...to handle more
sophisticated requirements.
In this case, the Perl and POD are using the text in the file
in an overlapping way, but still the Perl6 and POD6 parsers are
fully separate.
That's not the case. As Larry has confirmed recently, to each parser (perl6 or
Perl6::Pod::Parser) everything in a source file will be either Perl or Pod
(and never both). And the only place where the two parsers will disagree is
inside a Perl string that happens to contain a Pod block.
In the example you gave, both Perl 6 and Pod 6 would treat the line:
> =definition
> method eat(Food $meal) {...}
*only* as Pod. So those two lines are pure documentation, not executable code.
Damian
