There are two ways of approaching the annotations. The one, as used in HSE, is to define the positions so that the original source can be reconstructed.
The more useful/difficult option is to defined the annotations so that they can be used to reconstruct a properly formatted source file even when some major manipulations have been done to the AST. The means everything has to be relative, similar to the pretty-print library.
Each AST element/annotation must be self-contained, in that it can be rendered correctly relative to a (positive) starting (row,col) position at the top left, regardless of what these are.
Positions are all stored as instances of DeltaPos, which gives the row and column offset for the next element relative to the current position.
The current position is stored in the rendering state, and may be updated by either explicitly moving forward, or by printing at an absolute position.
The existing HSE ExactPrint rendering engine is used, which makes use of absolute positions.
Utility functions exist to print at a DeltaPos, which simply combine the current position with the delta to provide an absolute position.
This combining takes place in the exactP/exactPC instances, and it is up to the annotation generator and using instance to define the reference point.
Two options exist
a) Relative to the SrcSpan defining the Located AST element. b) Relative to the last output position
Option (a) makes sense for specific layout items that need vertical alignment, while option (b) makes sense for spacing withing say an expression where the name of one of the variables may eventually be changed.
Rule of thumb: use option (b) unless option (a) is required, it should result in a more resilient annotation when tools need to change things.
Comments should be pushed as low as possible down the AST.
Each annotation maintains a list of DComments, which are comments defined as being relative to the start of the containing AST element SrcSpan.
The rendering engine has an ordered list of comments which it inserts into the output stream as it advances.
Every time a new AST element/annotation is entered, the current position is taken as the start of the SrcSpan, and so the absolute positions of the comment can be determined. These are then merged into the list of comments for rendering.
Question: what happens if a sub-element changes size from the original? Later comments will then be in a different position.
Perhaps provide a list of lists, relative to the sub-items.
Option 1.
When generating the annotation, pass the remaining list of comments to the sub elements. Each sub-element (recursively) grabs the comments it takes responsibility for, and passes the balance back. Any comments fitting into the span but not allocated to a sub-element become allocated at this level, interspersed between the sub elements.
Option 2.
Do a hard separation of comments according to SrcSpan. So the parent element takes all comments in the parent SrcSpan that do not fit into any of the sub-element SrcSpans.
This has the disadvantage that a syntax element can become disconnected from its comments, e.g. a pre or post comment for a declaration.
Note: Because the position always moves forward when emitting source, and syntax element start points are used by exactPC to advance, there is a problem with preceding comments.