[omniORB] comments BEFORE or after decl, again

[Richard Gruet]

Hi everybody,

I come back with a proposition to fix my problem concerning the comments in the
OmniORB3 AST (they are related to the preceding declaration, whereas I'd like
them to be related to the following decl).

If we could visit the AST in the same order that declarations occured in the IDL
during parsing, it should be easy to hack the tree by shifting the comments to
get the desired order. The following program demonstrates this: calling
fixComments() add a new attribute 'preComments' to the AST nodes:


from omniidl import idlast, idlvisitor, idlutil
#----------------------------------------------
class CommentVisitor (idlvisitor.AstVisitor):
#----------------------------------------------
 def __init__(self):
  self.prevNode = None # last visited node

 def _visitNode(self, node):
  ''' Generic processing for all other nodes.
  '''
  self._fixComments(node)

 def _fixComments(self, node):
  node.preComments = ''
  if self.prevNode:
   try:
    node.preComments = self.prevNode.comments()
   except AttributeError: # Version < 3
    pass
  self.prevNode = node

 # Redefined visiting methods:
 def visitAST(self, node):
  self._fixComments(node)
  for n in node.declarations():
   n.accept(self)

 def visitModule(self, node):
  self._fixComments(node)
  for n in node.definitions():
   n.accept(self)

 def visitInterface(self, node):
  self._fixComments(node)
  for n in node.contents():
   n.accept(self)

 # All remaining nodes are simply alias:
 visitForward = visitConst = visitDeclarator = _visitNode
 visitTypedef = visitMember = visitStruct = _visitNode
 visitException = visitCaseLabel = visitUnionCase = _visitNode
 visitUnion = visitEnumerator = visitEnum = _visitNode
 visitAttribute = visitParameter = visitOperation = _visitNode
 visitNative = visitStateMember = visitFactory = _visitNode
 visitValueForward = visitValueBox = visitValueAbs = _visitNode
 visitValue = _visitNode
#end class

#----------------------------------------------
def fixComments(tree):
#----------------------------------------------
 ''' Hacks the AST by adding to the nodes an attribute 'preComments'
     which contains comments that occured BEFORE the declaration.
 '''
 visitor = CommentVisitor()
 tree.accept(visitor)


Of course, all this assumes that the traversal order is correct (ie same as
declaration order).
This solution doesn't require any change in Duncan's code; I agree with him that
creating specific nodes for comments whould raise many issues, and that some kind
of policy is needed concerning the order of comments (but I do think that 90%
people put their comments BEFORE, and Python doc convention is rather a
curiosity!)

Opinions ?

Cheers,
Richard Gruet


Duncan Grisby wrote:

> On Friday 17 March, Stefan Seefeld wrote:
>
> > One possibility to do this would be to make comments 'first class citizens'
> > in your AST. Then your visitor base class would need another method (which
> > probably is a noop in most cases) for visiting the comment.
>
> Unfortunately, I don't think that's very feasible, since comments are
> fundamentally different from other declarations. In particular, they
> can appear anywhere in the input, including in the middle of a
> declaration. Consider
>
>   interface I {
>     /* About to declare foo */
>     void /* No return type */ foo(long /* a long */ l);
>     /* foo has been declared */
>   };
>
> If comments appear as nodes in the AST, where should the ones above
> go?  The AST will have to be identical to the AST of either
>
>   interface I {
>     /* About to declare foo */
>     /* No return type */
>     void foo(/* a long */ long l);
>     /* foo has been declared */
>   };
>
> or
>
>   interface I {
>     /* About to declare foo */
>     void foo(long l /* a long */);
>     /* No return type */
>     /* foo has been declared */
>   };
>
> So the front-end has to have some idea of how comments are ordered
> relative to declarations. In my opinion, once it has that much
> knowledge, it might as well attach the comments directly to the
> declarations in question.
>
> Also, even if there is a policy for placing comments in the AST, lots
> of back-end code will have to be changed, since it doesn't all use the
> visitor pattern. Operation nodes are assumed to only contain Parameter
> nodes, for example. I don't think that back-ends should have to care
> at all that there might be comments embedded in the AST.
>
> Cheers,
>
> Duncan.
>
> --
>  -- Duncan Grisby  \  Research Engineer  --
>   -- AT&T Laboratories Cambridge          --
>    -- http://www.uk.research.att.com/~dpg1 --