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

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) {...}

     The A<method>() method has the following argument list: A<(..)>

In stead of

         method eat(Food $meal) {...}

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:

         method eat(Food $meal) {...}

      =for DESCRIPTION

With only a slight modification that is already valid Pod:


           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 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.


Reply via email to