> 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