API Annotations question
Alan, devs, since API annotations were added some data types in the source code have extra comments related to these annotations, eg. -- | A type or class declaration. data TyClDecl name = -- | @type/data family T :: *->*@ -- -- - 'ApiAnnotation.AnnKeywordId' : 'ApiAnnotation.AnnType', -- 'ApiAnnotation.AnnData', -- 'ApiAnnotation.AnnFamily','ApiAnnotation.AnnWhere', -- 'ApiAnnotation.AnnOpen','ApiAnnotation.AnnDcolon', -- 'ApiAnnotation.AnnClose' FamDecl { tcdFam :: FamilyDecl name } I'm totally clueless about what these comments mean. Where can I find an explanation? Couldn't find anything on the wiki. Janek
This has come up in the review of D538 too. Once processed by haddock the
online documentation links through to the hsSyn/ApiAnnotation module where
more detail is given.
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.
Alan
On Thu, Jan 15, 2015 at 3:16 PM, Jan Stolarek
Alan, devs,
since API annotations were added some data types in the source code have extra comments related to these annotations, eg.
-- | A type or class declaration. data TyClDecl name = -- | @type/data family T :: *->*@ -- -- - 'ApiAnnotation.AnnKeywordId' : 'ApiAnnotation.AnnType', -- 'ApiAnnotation.AnnData', -- 'ApiAnnotation.AnnFamily','ApiAnnotation.AnnWhere', -- 'ApiAnnotation.AnnOpen','ApiAnnotation.AnnDcolon', -- 'ApiAnnotation.AnnClose' FamDecl { tcdFam :: FamilyDecl name }
I'm totally clueless about what these comments mean. Where can I find an explanation? Couldn't find anything on the wiki.
Janek
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
All of the hsSyn ones. and the Wiki page is
https://ghc.haskell.org/trac/ghc/wiki/GhcAstAnnotations
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.
Alan
On Thu, Jan 15, 2015 at 3:48 PM, Jan Stolarek
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
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
participants (2)
-
Alan & Kim Zimmerman -
Jan Stolarek