> 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 <[email protected]>
>
> 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



_______________________________________________
ghc-devs mailing list
[email protected]
http://www.haskell.org/mailman/listinfo/ghc-devs

Reply via email to