Add docs to types (#81)

* Added missing module declarations. #37 * Process only those modules that are reachable from exposed ones. Remove package path from module names. #21 * Renaming concepts based on review feedback. #41 * Moved Advanced module up a level. #43 * Removed unused unindent function. * Moved name to SDK. * Added missing module to SDK. * Partial implementation of value mapping. * Ignore all generated JS. * Change extra arg position and naming. #46, #25 * Change extra arg position and naming. #46, #25 * Removed remaining references to extra. #5 * Change extra arg position. #46, #25, #5 * Added more coverage. #46, #25, #5 * Changes suggested in the PR. #46, #25, #5 * Use more explicit names. * All patterns supported. * Pattern-match supported. * Added support for SDK operators. #52 * Fix compile errors. * Prepare Elm module publishing. #2 * Fix repo name. #2 * Support for let expressions. #54 * Simple join implementations. #64 * Refactoring to make the code more organized. * Refactoring to make the code more organized. * Prepare value mapping utils. #53 * More descriptive naming. * More descriptive naming. * Removed unused function * Better naming * Added utility function and removed unused one. * Added variable resolution. * Hooked up variable resolution and updated tests. #53 * Completed reference resolution. #53 * Added missing docs and refactored. #68 * Document and refactor driven by the goal to process Morphir using Morphir. #68 * Various fixes. #68 * Report parse errors. * Updated docs. * Link to Elm package. * More documentation. * Moved out Literal and fixed codec. #75, #76 * Fix compile error. #75, #76 * Fix compile error. #75, #76 * Change naming convention for type tags. #77 * Add documentation to types. #7 * Better docs.
finos · May 26, 2020 · 7bece45 · 7bece45
2 parents 43b5e28 + 288b633
commit 7bece45
Show file tree

Hide file tree

Showing 18 changed files with 142 additions and 75 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,4 +1,4 @@
-## [0.4.1](https://github.com/Morgan-Stanley/morphir-elm/compare/v0.4.0...v0.4.1) (2020-05-22)
+## [0.4.2](https://github.com/Morgan-Stanley/morphir-elm/compare/v0.1.0...v0.4.2) (2020-05-26)
 
 
 ### Bug Fixes
@@ -8,19 +8,7 @@
 
 
 
-# [0.4.0](https://github.com/Morgan-Stanley/morphir-elm/compare/v0.3.4...v0.4.0) (2020-03-31)
-
-
-
-## [0.3.4](https://github.com/Morgan-Stanley/morphir-elm/compare/v0.3.3...v0.3.4) (2020-03-23)
-
-
-
-## [0.3.3](https://github.com/Morgan-Stanley/morphir-elm/compare/v0.3.2...v0.3.3) (2020-03-23)
-
-
-
-## [0.3.2](https://github.com/Morgan-Stanley/morphir-elm/compare/v0.3.1...v0.3.2) (2020-03-12)
+# 0.1.0 (2020-03-11)
 
 
 
diff --git a/README.md b/README.md
@@ -41,7 +41,7 @@ root directory with the following structure:
 
 ```
 {
-    "name": "package-name",
+    "name": "My.Package",
     "sourceDirectory": "src",
     "exposedModules": [
         "Foo",
@@ -50,6 +50,13 @@ root directory with the following structure:
 }
 ```
 
+* **name** - The name of the package. The package name should be a valid Elm module name and it should be used as a 
+module prefix in your Elm models. If your package name is `My.Package` all your module files should either be directly 
+under that or in submodules.
+* **sourceDirectory** - The directory where your Elm sources are located.
+* **exposedModules** - The list of modules in the public interface of the package. Module names should exclude the 
+common package prefix. In the above example `Foo` refers to the Elm module `My.Package.Foo`. 
+
 #### Options
 
 - `--project-dir <path>`, `-p`

diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "morphir-elm",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Elm bindings for Morphir",
   "scripts": {
     "test": "elm-test",

diff --git a/src/Morphir/Elm/Frontend.elm b/src/Morphir/Elm/Frontend.elm
@@ -20,6 +20,7 @@ import Json.Encode as Encode
 import Morphir.Elm.Frontend.Resolve as Resolve exposing (ModuleResolver, PackageResolver)
 import Morphir.Graph
 import Morphir.IR.AccessControlled exposing (AccessControlled, private, public)
+import Morphir.IR.Documented exposing (Documented)
 import Morphir.IR.FQName as FQName exposing (FQName(..), fQName)
 import Morphir.IR.Literal exposing (Literal(..))
 import Morphir.IR.Module as Module
@@ -382,7 +383,7 @@ mapProcessedFile currentPackagePath processedFile modulesSoFar =
                 [ ( SDK.packageName, SDK.packageSpec )
                 ]
 
-        typesResult : Result Errors (Dict Name (AccessControlled (Type.Definition SourceLocation)))
+        typesResult : Result Errors (Dict Name (AccessControlled (Documented (Type.Definition SourceLocation))))
         typesResult =
             mapDeclarationsToType processedFile.parsedFile.sourceFile moduleExpose (processedFile.file.declarations |> List.map Node.value)
                 |> Result.map Dict.fromList
@@ -419,7 +420,7 @@ mapProcessedFile currentPackagePath processedFile modulesSoFar =
             )
 
 
-mapDeclarationsToType : SourceFile -> Exposing -> List Declaration -> Result Errors (List ( Name, AccessControlled (Type.Definition SourceLocation) ))
+mapDeclarationsToType : SourceFile -> Exposing -> List Declaration -> Result Errors (List ( Name, AccessControlled (Documented (Type.Definition SourceLocation)) ))
 mapDeclarationsToType sourceFile expose decls =
     decls
         |> List.filterMap
@@ -456,8 +457,13 @@ mapDeclarationsToType sourceFile expose decls =
                                         typeParams =
                                             typeAlias.generics
                                                 |> List.map (Node.value >> Name.fromString)
+
+                                        doc =
+                                            typeAlias.documentation
+                                                |> Maybe.map (Node.value >> String.dropLeft 3 >> String.dropRight 2)
+                                                |> Maybe.withDefault ""
                                     in
-                                    ( name, withAccessControl isExposed (Type.typeAliasDefinition typeParams typeExp) )
+                                    ( name, withAccessControl isExposed (Documented doc (Type.typeAliasDefinition typeParams typeExp)) )
                                 )
                             |> Just
 
@@ -548,11 +554,16 @@ mapDeclarationsToType sourceFile expose decls =
                                         )
                                     |> ListOfResults.liftAllErrors
                                     |> Result.mapError List.concat
+
+                            doc =
+                                customType.documentation
+                                    |> Maybe.map (Node.value >> String.dropLeft 3 >> String.dropRight 2)
+                                    |> Maybe.withDefault ""
                         in
                         ctorsResult
                             |> Result.map
                                 (\constructors ->
-                                    ( name, withAccessControl isTypeExposed (Type.customTypeDefinition typeParams (withAccessControl isCtorExposed constructors)) )
+                                    ( name, withAccessControl isTypeExposed (Documented doc (Type.customTypeDefinition typeParams (withAccessControl isCtorExposed constructors))) )
                                 )
                             |> Just
 
@@ -1313,14 +1324,15 @@ resolveLocalNames moduleResolver moduleDef =
         rewriteValues variables value =
             resolveVariablesAndReferences variables moduleResolver value
 
-        typesResult : Result Errors (Dict Name (AccessControlled (Type.Definition SourceLocation)))
+        typesResult : Result Errors (Dict Name (AccessControlled (Documented (Type.Definition SourceLocation))))
         typesResult =
             moduleDef.types
                 |> Dict.toList
                 |> List.map
                     (\( typeName, typeDef ) ->
-                        typeDef.value
+                        typeDef.value.value
                             |> Type.mapDefinition rewriteTypes
+                            |> Result.map (Documented typeDef.value.doc)
                             |> Result.map (AccessControlled typeDef.access)
                             |> Result.map (Tuple.pair typeName)
                             |> Result.mapError List.concat

diff --git a/src/Morphir/Elm/Frontend/Resolve.elm b/src/Morphir/Elm/Frontend/Resolve.elm
@@ -172,8 +172,8 @@ createPackageResolver dependencies currentPackagePath currentPackageModules =
                                         |> Result.fromMaybe (CouldNotFindName packagePath modulePath typeName)
                                 )
                             |> Result.map
-                                (\typeDecl ->
-                                    case typeDecl of
+                                (\documentedTypeDecl ->
+                                    case documentedTypeDecl.value of
                                         Type.CustomTypeSpecification _ ctors ->
                                             ctors
                                                 |> List.map

diff --git a/src/Morphir/IR/Documented.elm b/src/Morphir/IR/Documented.elm
@@ -0,0 +1,17 @@
+module Morphir.IR.Documented exposing (..)
+
+{-| Tools to assign documentation to nodes in the IR.
+-}
+
+
+{-| Type that represents a documented value.
+-}
+type alias Documented a =
+    { doc : String
+    , value : a
+    }
+
+
+map : (a -> b) -> Documented a -> Documented b
+map f { doc, value } =
+    Documented doc (f value)
diff --git a/src/Morphir/IR/Documented/Codec.elm b/src/Morphir/IR/Documented/Codec.elm
@@ -0,0 +1,20 @@
+module Morphir.IR.Documented.Codec exposing (..)
+
+import Json.Decode as Decode
+import Json.Encode as Encode
+import Morphir.IR.Documented exposing (Documented)
+
+
+encodeDocumented : (a -> Encode.Value) -> Documented a -> Encode.Value
+encodeDocumented encodeValue d =
+    Encode.list identity
+        [ Encode.string d.doc
+        , encodeValue d.value
+        ]
+
+
+decodeDocumented : Decode.Decoder a -> Decode.Decoder (Documented a)
+decodeDocumented decodeValue =
+    Decode.map2 Documented
+        (Decode.index 1 Decode.string)
+        (Decode.index 2 decodeValue)
diff --git a/src/Morphir/IR/Module.elm b/src/Morphir/IR/Module.elm
@@ -12,6 +12,7 @@ module Morphir.IR.Module exposing
 
 import Dict exposing (Dict)
 import Morphir.IR.AccessControlled exposing (AccessControlled, withPublicAccess)
+import Morphir.IR.Documented as Documented exposing (Documented)
 import Morphir.IR.Name exposing (Name)
 import Morphir.IR.Path exposing (Path)
 import Morphir.IR.Type as Type exposing (Type)
@@ -26,7 +27,7 @@ type alias ModulePath =
 {-| Type that represents a module specification.
 -}
 type alias Specification a =
-    { types : Dict Name (Type.Specification a)
+    { types : Dict Name (Documented (Type.Specification a))
     , values : Dict Name (Value.Specification a)
     }
 
@@ -42,7 +43,7 @@ emptySpecification =
 {-| Type that represents a module definition. It includes types and values.
 -}
 type alias Definition a =
-    { types : Dict Name (AccessControlled (Type.Definition a))
+    { types : Dict Name (AccessControlled (Documented (Type.Definition a)))
     , values : Dict Name (AccessControlled (Value.Definition a))
     }
 
@@ -59,7 +60,7 @@ definitionToSpecification def =
                         |> withPublicAccess
                         |> Maybe.map
                             (\typeDef ->
-                                ( path, Type.definitionToSpecification typeDef )
+                                ( path, typeDef |> Documented.map Type.definitionToSpecification )
                             )
                 )
             |> Dict.fromList
@@ -95,7 +96,7 @@ mapSpecificationAttributes f spec =
         (spec.types
             |> Dict.map
                 (\_ typeSpec ->
-                    Type.mapSpecificationAttributes f typeSpec
+                    typeSpec |> Documented.map (Type.mapSpecificationAttributes f)
                 )
         )
         (spec.values
@@ -114,7 +115,7 @@ mapDefinitionAttributes f def =
             |> Dict.map
                 (\_ typeDef ->
                     AccessControlled typeDef.access
-                        (Type.mapDefinitionAttributes f typeDef.value)
+                        (typeDef.value |> Documented.map (Type.mapDefinitionAttributes f))
                 )
         )
         (def.values

diff --git a/src/Morphir/IR/Module/Codec.elm b/src/Morphir/IR/Module/Codec.elm
@@ -5,6 +5,7 @@ module Morphir.IR.Module.Codec exposing (..)
 import Dict
 import Json.Encode as Encode
 import Morphir.IR.AccessControlled.Codec exposing (encodeAccessControlled)
+import Morphir.IR.Documented.Codec exposing (encodeDocumented)
 import Morphir.IR.Module exposing (Definition, Specification)
 import Morphir.IR.Name.Codec exposing (encodeName)
 import Morphir.IR.Type.Codec as TypeCodec
@@ -20,9 +21,9 @@ encodeSpecification encodeAttributes spec =
                 |> Dict.toList
                 |> Encode.list
                     (\( name, typeSpec ) ->
-                        Encode.object
-                            [ ( "name", encodeName name )
-                            , ( "spec", TypeCodec.encodeSpecification encodeAttributes typeSpec )
+                        Encode.list identity
+                            [ encodeName name
+                            , typeSpec |> encodeDocumented (TypeCodec.encodeSpecification encodeAttributes)
                             ]
                     )
           )
@@ -31,9 +32,9 @@ encodeSpecification encodeAttributes spec =
                 |> Dict.toList
                 |> Encode.list
                     (\( name, valueSpec ) ->
-                        Encode.object
-                            [ ( "name", encodeName name )
-                            , ( "spec", ValueCodec.encodeSpecification encodeAttributes valueSpec )
+                        Encode.list identity
+                            [ encodeName name
+                            , valueSpec |> ValueCodec.encodeSpecification encodeAttributes
                             ]
                     )
           )
@@ -48,9 +49,9 @@ encodeDefinition encodeAttributes def =
                 |> Dict.toList
                 |> Encode.list
                     (\( name, typeDef ) ->
-                        Encode.object
-                            [ ( "name", encodeName name )
-                            , ( "def", encodeAccessControlled (TypeCodec.encodeDefinition encodeAttributes) typeDef )
+                        Encode.list identity
+                            [ encodeName name
+                            , typeDef |> encodeAccessControlled (encodeDocumented (TypeCodec.encodeDefinition encodeAttributes))
                             ]
                     )
           )
@@ -59,9 +60,9 @@ encodeDefinition encodeAttributes def =
                 |> Dict.toList
                 |> Encode.list
                     (\( name, valueDef ) ->
-                        Encode.object
-                            [ ( "name", encodeName name )
-                            , ( "def", encodeAccessControlled (ValueCodec.encodeDefinition encodeAttributes) valueDef )
+                        Encode.list identity
+                            [ encodeName name
+                            , valueDef |> encodeAccessControlled (ValueCodec.encodeDefinition encodeAttributes)
                             ]
                     )
           )

diff --git a/src/Morphir/IR/SDK/Bool.elm b/src/Morphir/IR/SDK/Bool.elm
@@ -1,6 +1,7 @@
 module Morphir.IR.SDK.Bool exposing (..)
 
 import Dict
+import Morphir.IR.Documented exposing (Documented)
 import Morphir.IR.Module as Module exposing (ModulePath)
 import Morphir.IR.Name as Name
 import Morphir.IR.Path as Path
@@ -18,7 +19,7 @@ moduleSpec : Module.Specification ()
 moduleSpec =
     { types =
         Dict.fromList
-            [ ( Name.fromString "Bool", OpaqueTypeSpecification [] )
+            [ ( Name.fromString "Bool", OpaqueTypeSpecification [] |> Documented "Type that represents a boolean value." )
             ]
     , values =
         Dict.empty

diff --git a/src/Morphir/IR/SDK/Char.elm b/src/Morphir/IR/SDK/Char.elm
@@ -1,6 +1,7 @@
 module Morphir.IR.SDK.Char exposing (..)
 
 import Dict
+import Morphir.IR.Documented exposing (Documented)
 import Morphir.IR.Module as Module exposing (ModulePath)
 import Morphir.IR.Name as Name
 import Morphir.IR.Path as Path
@@ -17,7 +18,7 @@ moduleSpec : Module.Specification ()
 moduleSpec =
     { types =
         Dict.fromList
-            [ ( Name.fromString "Char", OpaqueTypeSpecification [] )
+            [ ( Name.fromString "Char", OpaqueTypeSpecification [] |> Documented "Type that represents a single character." )
             ]
     , values =
         Dict.empty

diff --git a/src/Morphir/IR/SDK/Float.elm b/src/Morphir/IR/SDK/Float.elm
@@ -1,6 +1,7 @@
 module Morphir.IR.SDK.Float exposing (..)
 
 import Dict
+import Morphir.IR.Documented exposing (Documented)
 import Morphir.IR.Module as Module exposing (ModulePath)
 import Morphir.IR.Name as Name
 import Morphir.IR.Path as Path
@@ -18,7 +19,7 @@ moduleSpec : Module.Specification ()
 moduleSpec =
     { types =
         Dict.fromList
-            [ ( Name.fromString "Float", OpaqueTypeSpecification [] )
+            [ ( Name.fromString "Float", OpaqueTypeSpecification [] |> Documented "Type that represents a floating-point number." )
             ]
     , values =
         Dict.empty

diff --git a/src/Morphir/IR/SDK/Int.elm b/src/Morphir/IR/SDK/Int.elm
@@ -1,6 +1,7 @@
 module Morphir.IR.SDK.Int exposing (..)
 
 import Dict
+import Morphir.IR.Documented exposing (Documented)
 import Morphir.IR.Module as Module exposing (ModulePath)
 import Morphir.IR.Name as Name
 import Morphir.IR.Path as Path
@@ -18,7 +19,7 @@ moduleSpec : Module.Specification ()
 moduleSpec =
     { types =
         Dict.fromList
-            [ ( Name.fromString "Int", OpaqueTypeSpecification [] )
+            [ ( Name.fromString "Int", OpaqueTypeSpecification [] |> Documented "Type that represents an integer value." )
             ]
     , values =
         Dict.empty

diff --git a/src/Morphir/IR/SDK/List.elm b/src/Morphir/IR/SDK/List.elm
@@ -1,6 +1,7 @@
 module Morphir.IR.SDK.List exposing (..)
 
 import Dict
+import Morphir.IR.Documented exposing (Documented)
 import Morphir.IR.Module as Module exposing (ModulePath)
 import Morphir.IR.Name as Name
 import Morphir.IR.Path as Path
@@ -18,7 +19,7 @@ moduleSpec : Module.Specification ()
 moduleSpec =
     { types =
         Dict.fromList
-            [ ( Name.fromString "List", OpaqueTypeSpecification [ [ "a" ] ] )
+            [ ( Name.fromString "List", OpaqueTypeSpecification [ [ "a" ] ] |> Documented "Type that represents a list of values." )
             ]
     , values =
         Dict.empty

diff --git a/src/Morphir/IR/SDK/Maybe.elm b/src/Morphir/IR/SDK/Maybe.elm
@@ -1,6 +1,7 @@
 module Morphir.IR.SDK.Maybe exposing (..)
 
 import Dict
+import Morphir.IR.Documented exposing (Documented)
 import Morphir.IR.Module as Module exposing (ModulePath)
 import Morphir.IR.Name as Name
 import Morphir.IR.Path as Path exposing (Path)
@@ -22,6 +23,7 @@ moduleSpec =
                     [ Type.Constructor (Name.fromString "Just") [ ( [ "value" ], Type.Variable () (Name.fromString "a") ) ]
                     , Type.Constructor (Name.fromString "Nothing") []
                     ]
+                    |> Documented "Type that represents an optional value."
               )
             ]
     , values =