Merge pull request #57 from Kroisse/docstr-annotation-unification

Merge docs into annotations completely

nirum.cabal

@@ -24,6 +24,7 @@ library
                  ,     Nirum.Constructs.Annotation.Internal
                  ,     Nirum.Constructs.Declaration
                  ,     Nirum.Constructs.DeclarationSet
+                 ,     Nirum.Constructs.Docs
                  ,     Nirum.Constructs.Identifier
                  ,     Nirum.Constructs.Module
                  ,     Nirum.Constructs.ModulePath
@@ -72,7 +73,7 @@ test-suite spec
   main-is:             Spec.hs
   other-modules:       Nirum.CliSpec
                ,       Nirum.Constructs.AnnotationSpec
-               ,       Nirum.Constructs.DeclarationSpec
+               ,       Nirum.Constructs.DocsSpec
                ,       Nirum.Constructs.DeclarationSetSpec
                ,       Nirum.Constructs.IdentifierSpec
                ,       Nirum.Constructs.ModuleSpec
@@ -85,6 +86,7 @@ test-suite spec
                ,       Nirum.ParserSpec
                ,       Nirum.Targets.PythonSpec
                ,       Nirum.VersionSpec
+               ,       Util
   default-language:    Haskell2010
   default-extensions:  OverloadedStrings
   build-depends:       base                     >=4.7     && <5

src/Nirum/Constructs/Annotation.hs

@@ -22,7 +22,7 @@ import qualified Data.Set as S
 
 import Nirum.Constructs (Construct (toCode))
 import Nirum.Constructs.Annotation.Internal
-import Nirum.Constructs.Declaration (Docs (Docs), annotationDocsName, toText)
+import Nirum.Constructs.Docs (Docs (Docs), annotationDocsName, toText)
 import Nirum.Constructs.Identifier (Identifier)
 
 

src/Nirum/Constructs/Annotation/Internal.hs

@@ -11,7 +11,7 @@ import qualified Data.Text as T
 import Text.InterpolatedString.Perl6 (qq)
 
 import Nirum.Constructs (Construct (toCode))
-import Nirum.Constructs.Declaration (annotationDocsName)
+import Nirum.Constructs.Docs (annotationDocsName)
 import Nirum.Constructs.Identifier (Identifier)
 
 

src/Nirum/Constructs/Declaration.hs

@@ -1,53 +1,18 @@
 module Nirum.Constructs.Declaration ( Declaration
-                                    , Docs(Docs)
-                                    , annotationDocsName
+                                    , annotations
                                     , docs
                                     , name
-                                    , toCode
-                                    , toCodeWithPrefix
-                                    , toText
                                     ) where
 
-import Data.String (IsString(fromString))
-
-import qualified Data.Text as T
-
-import Nirum.Constructs (Construct(toCode))
-import Nirum.Constructs.Identifier (Identifier)
+import Nirum.Constructs (Construct)
+import Nirum.Constructs.Annotation (AnnotationSet, lookupDocs)
+import Nirum.Constructs.Docs (Docs)
 import Nirum.Constructs.Name (Name)
 
-annotationDocsName :: Identifier
-annotationDocsName = "docs"
-
 -- 'Construct' which has its own unique 'name' and can has its 'docs'.
 class Construct a => Declaration a where
-    name :: a -> Name
-    docs :: a -> Maybe Docs
-
--- | Docstring for constructs.
-data Docs = Docs T.Text deriving (Eq, Ord, Show)
-
--- | Convert the docs to text.
-toText :: Docs -> T.Text
-toText (Docs docs') = docs'
-
--- | Similar to 'toCode' except it takes 'Maybe Docs' instead of 'Docs'.
--- If the given docs is 'Nothing' it simply returns an empty string.
--- Otherwise it returns a code string with the prefix.
-toCodeWithPrefix :: T.Text     -- | The prefix to be prepended if not empty.
-                 -> Maybe Docs -- | The docs to convert to code.
-                 -> T.Text
-toCodeWithPrefix _ Nothing = ""
-toCodeWithPrefix prefix (Just docs') = T.append prefix $ toCode docs'
-
-instance Construct Docs where
-    toCode (Docs docs') = let d = if "\n" `T.isSuffixOf` docs'
-                                  then T.dropEnd 1 docs'
-                                  else docs'
-                          in T.append "# " $ T.replace "\n" "\n# " d
+    name        :: a -> Name
+    annotations :: a -> AnnotationSet
 
-instance IsString Docs where
-    fromString s = let t = T.pack s
-                   in Docs (if "\n" `T.isSuffixOf` t
-                            then t
-                            else t `T.snoc` '\n')
+docs :: Declaration a => a -> Maybe Docs
+docs = lookupDocs . annotations

src/Nirum/Constructs/Docs.hs

@@ -0,0 +1,45 @@
+{-# LANGUAGE OverloadedStrings #-}
+module Nirum.Constructs.Docs ( Docs(Docs)
+                             , annotationDocsName
+                             , toCode
+                             , toCodeWithPrefix
+                             , toText
+                             ) where
+
+import Data.String (IsString(fromString))
+
+import qualified Data.Text as T
+
+import Nirum.Constructs (Construct(toCode))
+import Nirum.Constructs.Identifier (Identifier)
+
+annotationDocsName :: Identifier
+annotationDocsName = "docs"
+
+-- | Docstring for constructs.
+data Docs = Docs T.Text deriving (Eq, Ord, Show)
+
+-- | Convert the docs to text.
+toText :: Docs -> T.Text
+toText (Docs docs') = docs'
+
+-- | Similar to 'toCode' except it takes 'Maybe Docs' instead of 'Docs'.
+-- If the given docs is 'Nothing' it simply returns an empty string.
+-- Otherwise it returns a code string with the prefix.
+toCodeWithPrefix :: T.Text     -- | The prefix to be prepended if not empty.
+                 -> Maybe Docs -- | The docs to convert to code.
+                 -> T.Text
+toCodeWithPrefix _ Nothing = ""
+toCodeWithPrefix prefix (Just docs') = T.append prefix $ toCode docs'
+
+instance Construct Docs where
+    toCode (Docs docs') = let d = if "\n" `T.isSuffixOf` docs'
+                                  then T.dropEnd 1 docs'
+                                  else docs'
+                          in T.append "# " $ T.replace "\n" "\n# " d
+
+instance IsString Docs where
+    fromString s = let t = T.pack s
+                   in Docs (if "\n" `T.isSuffixOf` t
+                            then t
+                            else t `T.snoc` '\n')

src/Nirum/Constructs/Module.hs

@@ -13,7 +13,7 @@ import Text.InterpolatedString.Perl6 (q)
 
 import Nirum.Constructs (Construct(toCode))
 import Nirum.Constructs.Annotation (empty)
-import Nirum.Constructs.Declaration (Docs)
+import Nirum.Constructs.Docs (Docs)
 import qualified Nirum.Constructs.DeclarationSet as DS
 import Nirum.Constructs.Identifier (Identifier)
 import Nirum.Constructs.ModulePath (ModulePath)

src/Nirum/Constructs/Service.hs

@@ -12,31 +12,29 @@ module Nirum.Constructs.Service ( Method ( Method
 import qualified Data.Text as T
 
 import Nirum.Constructs (Construct(toCode))
-import Nirum.Constructs.Annotation (AnnotationSet, lookupDocs)
-import Nirum.Constructs.Declaration ( Declaration(name, docs)
-                                    , Docs
-                                    , toCodeWithPrefix
-                                    )
+import Nirum.Constructs.Annotation (AnnotationSet, empty, lookupDocs)
+import Nirum.Constructs.Declaration (Declaration(annotations, name), docs)
+import Nirum.Constructs.Docs (Docs, toCodeWithPrefix)
 import Nirum.Constructs.DeclarationSet (DeclarationSet, toList)
 import Nirum.Constructs.Name (Name)
 import Nirum.Constructs.TypeExpression (TypeExpression)
 
 -- | 'Method' parameter.
-data Parameter = Parameter Name TypeExpression (Maybe Docs)
+data Parameter = Parameter Name TypeExpression AnnotationSet
                  deriving (Eq, Ord, Show)
 
 instance Construct Parameter where
-    toCode (Parameter name' typeExpr docs') =
+    toCode p@(Parameter name' typeExpr _) =
         T.concat [ toCode typeExpr
                  , " "
                  , toCode name'
                  , ","
-                 , toCodeWithPrefix "\n" docs'
+                 , toCodeWithPrefix "\n" (docs p)
                  ]
 
 instance Declaration Parameter where
     name (Parameter name' _ _) = name'
-    docs (Parameter _ _ docs') = docs'
+    annotations (Parameter _ _ anno') = anno'
 
 -- | 'Service' method.
 data Method = Method { methodName :: Name
@@ -60,15 +58,14 @@ instance Construct Method where
                    , toCode $ methodName method
                    , " ("
                    , toCodeWithPrefix "\n  " docs'
-                   ] ++ case (docs', params') of
+                   ] ++ case (docs method, params') of
                             (Nothing, []) -> []
                             (Just _, []) -> ["\n"]
-                            (Nothing, [p@(Parameter _ _ Nothing)]) ->
-                                [T.dropWhileEnd (== ',') $ toCode p]
-                            _ -> [ "\n"
-                                 , T.intercalate "\n" $ map indentedCode params'
-                                 , "\n"
-                                 ]
+                            (Nothing, [p@(Parameter _ _ anno')]) ->
+                                if anno' == empty
+                                then [T.dropWhileEnd (== ',') $ toCode p]
+                                else verboseForm params'
+                            _ -> verboseForm params'
                    ++ [")"]
                    ++ case error' of
                           Nothing -> []
@@ -78,15 +75,20 @@ instance Construct Method where
         params' :: [Parameter]
         params' = toList params
         docs' :: Maybe Docs
-        docs' = lookupDocs annotationSet'
+        docs' = docs method
         indentedCode :: Construct a => a -> T.Text
         indentedCode c = T.concat [ "  "
                                   , T.intercalate "\n  " $ T.lines (toCode c)
                                   ]
+        verboseForm :: [Parameter] -> [T.Text]
+        verboseForm p = [ "\n"
+                        , T.intercalate "\n" $ map indentedCode p
+                        , "\n"
+                        ]
 
 instance Declaration Method where
     name = methodName
-    docs = methodDocs
+    annotations = methodAnnotations
 
 -- | RPC service.
 data Service =

src/Nirum/Constructs/TypeDeclaration.hs

@@ -24,12 +24,9 @@ import Data.String (IsString(fromString))
 import qualified Data.Text as T
 
 import Nirum.Constructs (Construct(toCode))
-import qualified Nirum.Constructs.Annotation as A
-import Nirum.Constructs.Annotation (AnnotationSet)
-import Nirum.Constructs.Declaration ( Declaration (..)
-                                    , Docs (..)
-                                    , toCodeWithPrefix
-                                    )
+import Nirum.Constructs.Annotation as A (AnnotationSet, empty, lookupDocs)
+import Nirum.Constructs.Declaration (Declaration(..), docs)
+import Nirum.Constructs.Docs (Docs(..), toCodeWithPrefix)
 import Nirum.Constructs.DeclarationSet (DeclarationSet, null', toList)
 import Nirum.Constructs.Identifier (Identifier)
 import Nirum.Constructs.ModulePath (ModulePath)
@@ -52,52 +49,53 @@ data Type
     deriving (Eq, Ord, Show)
 
 -- | Member of 'EnumType'.
-data EnumMember = EnumMember Name (Maybe Docs) deriving (Eq, Ord, Show)
+data EnumMember = EnumMember Name AnnotationSet deriving (Eq, Ord, Show)
 
 instance Construct EnumMember where
-    toCode (EnumMember name' docs') = T.concat [ toCode name'
-                                               , toCodeWithPrefix "\n" docs'
-                                               ]
+    toCode e@(EnumMember name' _) = T.concat [ toCode name'
+                                             , toCodeWithPrefix "\n" (docs e)
+                                             ]
 
 instance Declaration EnumMember where
     name (EnumMember name' _) = name'
-    docs (EnumMember _ docs') = docs'
+    annotations (EnumMember _ anno') = anno'
 
 instance IsString EnumMember where
-    fromString s = EnumMember (fromString s) Nothing
+    fromString s = EnumMember (fromString s) A.empty
 
 -- | Field of 'RecordType' and 'Tag'.
-data Field = Field Name TypeExpression (Maybe Docs) deriving (Eq, Ord, Show)
+data Field = Field Name TypeExpression AnnotationSet deriving (Eq, Ord, Show)
 
 instance Construct Field where
-    toCode (Field name' typeExpr docs') = T.concat [ toCode typeExpr
-                                                   , " "
-                                                   , toCode name'
-                                                   , ","
-                                                   , toCodeWithPrefix "\n" docs'
-                                                   ]
+    toCode field@(Field name' typeExpr _) =
+        T.concat [ toCode typeExpr
+                 , " "
+                 , toCode name'
+                 , ","
+                 , toCodeWithPrefix "\n" (docs field)
+                 ]
 
 instance Declaration Field where
     name (Field name' _ _) = name'
-    docs (Field _ _ docs') = docs'
+    annotations (Field _ _ anno') = anno'
 
 -- | Tag of 'UnionType'.
-data Tag = Tag Name (DeclarationSet Field) (Maybe Docs) deriving (Eq, Ord, Show)
+data Tag = Tag Name (DeclarationSet Field) AnnotationSet deriving (Eq, Ord, Show)
 
 instance Construct Tag where
-    toCode (Tag name' fields' docs') =
+    toCode tag@(Tag name' fields' _) =
         if null' fields'
-        then T.concat [toCode name', toCodeWithPrefix "\n" docs']
+        then T.concat [toCode name', toCodeWithPrefix "\n" (docs tag)]
         else T.concat [ toCode name'
                       , " (", fieldsCode, ")"
-                      , toCodeWithPrefix "\n" docs'
+                      , toCodeWithPrefix "\n" (docs tag)
                       ]
       where
         fieldsCode = T.intercalate " " $ map toCode $ toList fields'
 
 instance Declaration Tag where
     name (Tag name' _ _) = name'
-    docs (Tag _ _ docs') = docs'
+    annotations (Tag _ _ anno') = anno'
 
 -- | Primitive type identifiers.
 data PrimitiveTypeIdentifier
@@ -221,6 +219,6 @@ instance Declaration TypeDeclaration where
     name TypeDeclaration { typename = name' } = name'
     name ServiceDeclaration { serviceName = name' } = name'
     name Import { importName = id' } = Name id' id'
-    docs TypeDeclaration { typeAnnotations = anno' } = A.lookupDocs anno'
-    docs ServiceDeclaration { serviceAnnotations = anno' } = A.lookupDocs anno'
-    docs Import { } = Nothing
+    annotations TypeDeclaration { typeAnnotations = anno' } = anno'
+    annotations ServiceDeclaration { serviceAnnotations = anno' } = anno'
+    annotations Import { } = A.empty

src/Nirum/Package.hs

@@ -22,7 +22,7 @@ import qualified Data.Set as S
 import System.Directory (doesDirectoryExist, listDirectory)
 import System.FilePath ((</>))
 
-import Nirum.Constructs.Declaration (Docs)
+import Nirum.Constructs.Docs (Docs)
 import qualified Nirum.Constructs.DeclarationSet as DS
 import Nirum.Constructs.Identifier (Identifier)
 import qualified Nirum.Constructs.Module as Mod