|
| 1 | +{-# LANGUAGE CPP #-} |
| 2 | +{-# LANGUAGE DuplicateRecordFields #-} |
| 3 | +{-# LANGUAGE LambdaCase #-} |
| 4 | +{-# LANGUAGE OverloadedStrings #-} |
| 5 | + |
| 6 | +module Ide.Plugin.HaddockComments.Data |
| 7 | + ( genForDataDecl |
| 8 | + ) where |
| 9 | + |
| 10 | +import Control.Monad (unless, when) |
| 11 | +import Control.Monad.Trans.Class (lift) |
| 12 | +import Data.Data (Data) |
| 13 | +import Data.Foldable (for_) |
| 14 | +import Data.List (isPrefixOf) |
| 15 | +import qualified Data.Map.Strict as Map |
| 16 | +import Data.Maybe (fromMaybe, isJust) |
| 17 | +import Development.IDE (realSpan) |
| 18 | +import Development.IDE.GHC.Compat |
| 19 | +import Development.IDE.GHC.ExactPrint |
| 20 | +import Ide.Plugin.HaddockComments.Prelude |
| 21 | +import Language.Haskell.GHC.ExactPrint |
| 22 | +import Language.Haskell.GHC.ExactPrint.Types hiding (GhcPs) |
| 23 | +import Language.Haskell.GHC.ExactPrint.Utils (mkComment) |
| 24 | + |
| 25 | +genForDataDecl :: GenComments |
| 26 | +genForDataDecl = |
| 27 | + GenComments { |
| 28 | + title = "Generate haddock comments", |
| 29 | + updateAnns = updateDataAnns |
| 30 | + } |
| 31 | + |
| 32 | +updateDataAnns :: LHsDecl GhcPs -> TransformT Maybe () |
| 33 | +updateDataAnns decl@(L declLoc (TyClD _ DataDecl {tcdDataDefn = HsDataDefn { dd_cons = cons }})) = do |
| 34 | + -- skip if all constructors and fields already have a haddock comment |
| 35 | + getAnnsT >>= (\anns -> unless (missingSomeHaddock anns cons) (lift Nothing)) |
| 36 | + |
| 37 | + -- visit each constructor and field |
| 38 | + addHaddockCommentsToList True declLoc (G AnnVbar) cons |
| 39 | + for_ cons $ \case |
| 40 | + L conLoc ConDeclH98 { con_args = RecCon (L _ fields) } -> addHaddockCommentsToList False conLoc (G AnnComma) fields |
| 41 | + _ -> pure () |
| 42 | + modifyAnnsT $ Map.adjust (\ann -> ann {annPriorComments = []}) (mkAnnKey decl) |
| 43 | +updateDataAnns _ = lift Nothing |
| 44 | + |
| 45 | +-- | Add haddock comments to a list of nodes |
| 46 | +addHaddockCommentsToList |
| 47 | + :: (Data a, Monad m) |
| 48 | + => Bool -- ^ If true, for each node, use previous node in the list as the anchor. Otherwise, use the outer node |
| 49 | + -> SrcSpan -- ^ The outer node |
| 50 | + -> KeywordId -- ^ The seperator between adjacent nodes |
| 51 | + -> [Located a] -- ^ The list of nodes. Haddock comments will be added to each of them |
| 52 | + -> TransformT m () |
| 53 | +addHaddockCommentsToList usePrevNodeAsAnchor outerLoc seperator nodes = |
| 54 | + -- If you want to understand this function, please first read this page carefully: |
| 55 | + -- https://hackage.haskell.org/package/ghc-exactprint-0.6.4/docs/Language-Haskell-GHC-ExactPrint-Delta.html |
| 56 | + -- The important part is that for DP(r,c), if r is zero, c is the offset start from the end of the previous node. |
| 57 | + -- However, if r is greater than zero, c is the offset start from the 'anchor'. |
| 58 | + -- Generally speaking, the 'anchor' is the node that "enclose" the current node. But it's not always the case. |
| 59 | + -- Sometimes 'anchor' is just the previous node. It depends on the the syntactic structure. |
| 60 | + -- For constructors, the anchor is the previous node (if there is any). |
| 61 | + -- For record fields, the anchor is always the constructor they belong to. |
| 62 | + for_ (zip nodes (Nothing: fmap Just nodes)) $ \(node, prevNode) -> do |
| 63 | + addHaddockCommentToCurrentNode <- fmap (not . fromMaybe True . flip hasHaddock node) getAnnsT |
| 64 | + -- We don't add new haddock comments to nodes with existing ones. |
| 65 | + when addHaddockCommentToCurrentNode $ do |
| 66 | + -- 'sameLineAsPrev' is a flag to determine the inline case, for example: |
| 67 | + -- data T = A { a :: Int, b :: String } | B { b :: Double } |
| 68 | + -- Note that it's a 'Maybe (Located a)', containing the previous node if the current node |
| 69 | + -- and the previous node are on the same line. |
| 70 | + -- |
| 71 | + -- For the multiline case (which is the most common), we keep the original indentation of each constructor |
| 72 | + -- and field. |
| 73 | + -- |
| 74 | + -- For the inline case, we use the first construcotr/field as the base, and align all following items |
| 75 | + -- to them. |
| 76 | + let sameLineAsPrev = prevNode >>= ( |
| 77 | + \prevNode' -> if notSeperatedByLineEnding prevNode' node |
| 78 | + then pure prevNode' |
| 79 | + else Nothing |
| 80 | + ) |
| 81 | + -- For the inline case, we need to move the seperator to the next line. |
| 82 | + -- For constructors, it's vertical bar; for fields, it's comma. |
| 83 | + -- The seperator is passed in as function argument. |
| 84 | + when (isJust sameLineAsPrev) $ modifyAnnsT $ \anns -> |
| 85 | + let newSepCol :: Annotation -> Int |
| 86 | + newSepCol ann = |
| 87 | + if usePrevNodeAsAnchor then 0 else deltaColumn (annEntryDelta ann) |
| 88 | + updateSepAnn :: Annotation -> Annotation |
| 89 | + updateSepAnn ann = ann {annsDP = |
| 90 | + Map.toList . Map.adjust (const $ DP (1, newSepCol ann)) seperator . Map.fromList $ annsDP ann} |
| 91 | + in flip (maybe anns) prevNode $ \prevNode' -> Map.adjust updateSepAnn (mkAnnKey prevNode') anns |
| 92 | + -- Calculate the real column of the anchor |
| 93 | + let anchorCol = maybe 0 srcSpanStartCol . realSpan . maybe outerLoc getLoc $ |
| 94 | + if usePrevNodeAsAnchor then prevNode else Nothing |
| 95 | + -- 'dpCol' is what we will use for the current node's entry delta's column |
| 96 | + dpCol <- flip fmap getAnnsT $ \anns -> |
| 97 | + case sameLineAsPrev of |
| 98 | + Just prevNode' -> |
| 99 | + -- If the previous node is the anchor, using 0 as column will make current code align with |
| 100 | + -- the previous one. |
| 101 | + -- Otherwise, use the column of entry delta of the previous node. |
| 102 | + -- The map lookup should not fail. '2' is used as a fallback value to make sure the syntax |
| 103 | + -- is correct after the changes. |
| 104 | + if usePrevNodeAsAnchor then 0 else maybe 2 (deltaColumn . annEntryDelta) |
| 105 | + $ anns Map.!? mkAnnKey prevNode' |
| 106 | + -- We subtract the real column to get dp column. |
| 107 | + Nothing -> (maybe 2 srcSpanStartCol . realSpan $ getLoc node) - anchorCol |
| 108 | + -- Modify the current node |
| 109 | + modifyAnnsT $ |
| 110 | + let updateCurrent :: Annotation -> Annotation |
| 111 | + updateCurrent ann = ann { |
| 112 | + -- If there exist non-haddock comments, we simply inherit the first one's delta pos, |
| 113 | + -- and move them two lines below, to seperate them from our newly added haddock comments |
| 114 | + -- Otherwise, inherit the node's entry delta pos. |
| 115 | + annPriorComments = case annPriorComments ann of |
| 116 | + (c, dp) : rem -> (emptyPriorHaddockComment, dp) : (c, DP (2,0)) : rem |
| 117 | + _ -> [(emptyPriorHaddockComment, annEntryDelta ann)], |
| 118 | + annEntryDelta = DP (1, dpCol) |
| 119 | + } |
| 120 | + in Map.adjust updateCurrent (mkAnnKey node) |
| 121 | + |
| 122 | +-- | Determine if a list of constructor declarations is missing some haddock comments. |
| 123 | +missingSomeHaddock :: Anns -> [LConDecl GhcPs] -> Bool |
| 124 | +missingSomeHaddock anns = any $ \lcon@(L _ conDecl) -> case conDecl of |
| 125 | + ConDeclH98 { con_args = RecCon (L _ fields) } -> |
| 126 | + elem (Just False) $ hasHaddock anns lcon : fmap (hasHaddock anns) fields |
| 127 | + _ -> False -- GADT is not supported yet |
| 128 | + |
| 129 | +-- | Returns 'True' if the end of the first node and the start of the second node are on the same line. |
| 130 | +notSeperatedByLineEnding :: Located a |
| 131 | + -> Located a |
| 132 | + -> Bool |
| 133 | +notSeperatedByLineEnding (L (RealSrcSpan x _) _) (L (RealSrcSpan y _) _) = |
| 134 | + srcLocLine (realSrcSpanEnd x) == srcLocLine (realSrcSpanStart y) |
| 135 | +notSeperatedByLineEnding _ _ = False |
| 136 | + |
| 137 | +-- | Empty haddock, suitable for being added to 'annPriorComments' |
| 138 | +emptyPriorHaddockComment :: Comment |
| 139 | +emptyPriorHaddockComment = mkComment "-- |" |
| 140 | +#if MIN_VERSION_ghc(9,0,0) |
| 141 | + badRealSrcSpan |
| 142 | +#else |
| 143 | + noSrcSpan |
| 144 | +#endif |
| 145 | + |
| 146 | +-- | Determines the given node has haddock comments attached to it. |
| 147 | +hasHaddock :: Data a => Anns -> Located a -> Maybe Bool |
| 148 | +hasHaddock anns node = fmap annHasHaddock (anns Map.!? key) |
| 149 | + where |
| 150 | + key = mkAnnKey node |
| 151 | + annHasHaddock ann = |
| 152 | + any (matchCommentPrefix priorCommentPrefix . fst) (annPriorComments ann) |
| 153 | + || any (matchCommentPrefix followingCommentPrefix . fst) (annFollowingComments ann) |
| 154 | + || any (keywordIdIsHaddockComment . fst) (annsDP ann) |
| 155 | + |
| 156 | +-- | Checks if the given 'KeywordId' is a comment, and specifically, a haddock comment. |
| 157 | +keywordIdIsHaddockComment :: KeywordId -> Bool |
| 158 | +keywordIdIsHaddockComment (AnnComment comment) = any (`isPrefixOf` commentContents comment) (priorCommentPrefix ++ followingCommentPrefix) |
| 159 | +keywordIdIsHaddockComment _ = False |
| 160 | + |
| 161 | +priorCommentPrefix :: [String] |
| 162 | +priorCommentPrefix = ["-- |", "{-|", "{- |"] |
| 163 | + |
| 164 | +followingCommentPrefix :: [String] |
| 165 | +followingCommentPrefix = ["-- ^", "{-^", "{- ^"] |
| 166 | + |
| 167 | +matchCommentPrefix :: [String] -> Comment -> Bool |
| 168 | +matchCommentPrefix prefix comment = any (`isPrefixOf` commentContents comment) prefix |
![mergify[bot]](https://avatars.githubusercontent.com/in/10562?v=4&size=40){kind=avatar}
0 commit comments