Re: [Grammatica-users] Feature request (more meaningful javadoc)

[Per Cederberg]

This is a very good suggestion. A variant of it has been
discussed before, although I don't quite remember if it
was on this list or in some private conversation I had.
It is also somewhat implemented in the parser generator
SableCC.

Basically the idea is to generate a type-safe analyzer:

  protected Node exitPrimeMeridian(PrimeMeridianProduction node)
      throws ParseException {

      return node;
  }

Where the class PrimeMeridianProduction contains:

  public Token getPrimemK();
  public Token getLeftParen();
  public NameProduction getName();
  public Token getComma();
  public LongitudeProduction getLongitude();
  public Token getRightParen();

This way, changes in the grammar are more likely to
cause compilation errors in the Analyzer classes. Which
is much better than the current run-time errors. It
also lends itself much better to documentation.

There has been no work yet in this direction in
Grammatica, so the exact details remain to be drawn
out. I always wanted to combine the above with a
simplification to the grammar format, allowing only
two types of productions:

  Choice = FirstAlternative
         | SecondAlternative
         ...
         | LastAlternative ;

  Sequence = First Second ... Last ;

This model fits perfectly with the type-safe nodes,
since all the FirstAlternative, SecondAlternative,
etc. nodes will then inherit ChoiceProduction. Which
is very object oriented. (Not my idea, saw it in a
paper on compiler generators.)

Anyway. These are my thoughts about it. Someone
should probably write it down more formally and
register a future improvement bug about this. Or
even implement some prototype?

Thanks for reading this far.

/Per

Yakov Keselman wrote:
> Hello Per,
>
> one feature I'd like to request (unless it has been
> requested before) is a more meaningful javadoc to be
> generated for production methods. Here is hopefully an
> explanatory example.
>
> Consider the following production (in your syntax):
>
> PrimeMeridian = PRIMEM_K LEFT_PAREN Name "," Longitude
> RIGHT_PAREN ;
>
> PRIMEM_K, LEFT_PAREN, ",", and RIGHT_PAREN are all
> terminals (atoms). Name and Longitude are
> non-terminals. Currently generated stub for
> exitPrimeMeridian is shown below.
>
>     /**
>      * Called when exiting a parse tree node.
>      * 
>      * @param node           the node being exited
>      * 
>      * @return the node to add to the parse tree, or
>      *         null if no parse tree should be created
>      * 
>      * @throws ParseException if the node analysis
> discovered errors
>      */
>     protected Node exitPrimeMeridian(Production node)
>         throws ParseException {
>
>         return node;
>     }
>
> I think that it will be more useful to have something
> like this (note the production included in javadoc and
> numbering of its children): 
>
>     /**
>      * Called when exiting a parse tree node.
>      * 
>      * @param node           the node being exited
>      * 
>      * PrimeMeridian = PRIMEM_K [0]  LEFT_PAREN [1] 
> Name [2]  "," [3]  Longitude [4]  RIGHT_PAREN [5] ;
>      */
>     protected Node exitPrimeMeridian(Production node)
> throws ParseException {
>
>         return node;
>     }
>
>
> Perhaps even more useful can be something of this
> kind:
>
>     protected Node exitPrimeMeridian( node primem_k,
> node left_paren, node name, node comma, node
> longitude, node right_paren ){ ... }
>
>
> Would the first or the second suggestion be difficult
> to implement? Has anyone else requested or thought
> about this?
>
> Thanks,
>
> = Yakov
>
>
> http://www.kinderspirit.org/yakovkeselman/
>
> ====
>
> Nothing is so firmly believed as that which we least know.
> -- Michel de Montaigne
>
>
>
>
>
> _______________________________________________
> Grammatica-users mailing list
> address@hidden
> http://lists.nongnu.org/mailman/listinfo/grammatica-users