API Annotations question

[Jan Stolarek]

> and the Wiki page is https://ghc.haskell.org/trac/ghc/wiki/GhcAstAnnotations
I read this page and I don't feel it answers my questions as it mostly seems to talk about the 
design. As a side note I don't understand the discussion of the design either. Eg. the wiki page 
lists four helper functions in the parser - gj, gl, aa, ams - but does not show how to use them 
and omits several other functions from the parser.

> They need to be updated whenever the Parser.y changes in a way that one of
> the keywords that is not otherwise captured in the AST is introduced, or
> moved.

1. How should I update the comment? For example I see that the list of annotations in the comment 
is preceeded with a dash. Is that mandatory? Why some annotations are separated by a colon and 
some by a comma:

    --  - 'ApiAnnotation.AnnKeywordId' : 'ApiAnnotation.AnnType',
    --             'ApiAnnotation.AnnData',

2. How can I verify that my comments is correct? How do errors manifest?

Is there a source code note that answers these questions? Are there any examples showing what to 
do when?

All in all I feel totally lost with annotations. When changing the parser I'm mostly doing trial 
and error because I still don't know how to use all annotation functions in the parser. I'm 
struggling to understand this but haddock comments in the parser don't suffice for me.

Janek

>
> Alan
>
> On Thu, Jan 15, 2015 at 3:48 PM, Jan Stolarek <jan.stolarek at p.lodz.pl>
>
> wrote:
> > > I am not sure what the best way is to add an internal source code link
> > > to it too without disturbing the haddock. I am open for suggestions.
> >
> > For me as a developer the most important thing is when and how do I need
> > to add/modify these
> > comments when working with the source code? First place where I started
> > looking was the wiki but
> > surprisingly I couldn't find a page about API annotations. Does such a
> > page exist?
> > The best thing IMO would be to add for each data type reference to a Note
> > that explains how to
> > work with these annotations. But I'm not sure if that's feasible. How
> > many data types have these
> > annotations?
> >
> > Janek