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
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