Merge pull request #49 from jfmengels/doc-improvements

Improve documentation

preview/src/ReviewConfig.elm

@@ -26,16 +26,17 @@ import Review.Rule exposing (Rule)
 import String.Extra
 
 
-
-config = configMagicLinkAuth "Jim Carlson" "jxxcarlson" "[email protected]"
+config =
+    configMagicLinkAuth "Jim Carlson" "jxxcarlson" "[email protected]"
 
 
 configMagicLinkAuth fullname username email =
-    configAll {fullname = fullname, username = username, email = email }
+    configAll { fullname = fullname, username = username, email = email }
+
 
 stringifyAdminConfig : { fullname : String, username : String, email : String } -> String
 stringifyAdminConfig { fullname, username, email } =
-    "{ fullname = " ++ String.Extra.quote fullname ++ ", username = " ++ String.Extra.quote username ++ ", email = " ++ String.Extra.quote email ++"}"
+    "{ fullname = " ++ String.Extra.quote fullname ++ ", username = " ++ String.Extra.quote username ++ ", email = " ++ String.Extra.quote email ++ "}"
 
 
 configAll : { fullname : String, username : String, email : String } -> List Rule
@@ -199,7 +200,7 @@ configAuthFrontend =
 
 
 configAuthBackend : { fullname : String, username : String, email : String } -> List Rule
-configAuthBackend adminConfig=
+configAuthBackend adminConfig =
     [ ClauseInCase.config "Backend" "update" "AuthBackendMsg authMsg" "Auth.Flow.backendUpdate (MagicLink.Auth.backendConfig model) authMsg" |> ClauseInCase.makeRule
     , ClauseInCase.config "Backend" "update" "AutoLogin sessionId loginData" "( model, Lamdera.sendToFrontend sessionId (AuthToFrontend <| Auth.Common.AuthSignInWithTokenResponse <| Ok <| loginData) )" |> ClauseInCase.makeRule
     , ClauseInCase.config "Backend" "update" "OnConnected sessionId clientId" "( model, Reconnect.connect model sessionId clientId )" |> ClauseInCase.makeRule
@@ -238,7 +239,6 @@ configAuthBackend adminConfig=
     ]
 
 
-
 configRoute : List Rule
 configRoute =
     [ -- ROUTE

review/elm.json

@@ -10,22 +10,29 @@
             "elm/json": "1.1.3",
             "elm/project-metadata-utils": "1.0.2",
             "jfmengels/elm-review": "2.14.0",
+            "jfmengels/elm-review-common": "1.3.3",
             "jfmengels/elm-review-debug": "1.0.8",
             "jfmengels/elm-review-documentation": "2.0.4",
             "jfmengels/elm-review-unused": "1.2.3",
             "jxxcarlson/elm-review-codeinstaller": "1.0.0",
             "stil4m/elm-syntax": "7.3.2"
         },
         "indirect": {
+            "BrianHicks/elm-trend": "2.1.3",
+            "elm/browser": "1.0.2",
             "elm/bytes": "1.0.8",
             "elm/html": "1.0.0",
             "elm/parser": "1.1.0",
             "elm/random": "1.0.0",
             "elm/regex": "1.0.0",
             "elm/time": "1.0.0",
+            "elm/url": "1.0.0",
             "elm/virtual-dom": "1.0.3",
+            "elm-explorations/benchmark": "1.0.2",
             "elm-explorations/test": "2.2.0",
+            "mdgriffith/style-elements": "5.0.2",
             "miniBill/elm-unicode": "1.1.1",
+            "robinheghan/murmur3": "1.0.0",
             "rtfeldman/elm-hex": "1.0.0",
             "stil4m/structured-writer": "1.0.3"
         }

review/src/ReviewConfig.elm

@@ -1,11 +1,12 @@
 module ReviewConfig exposing (config)
 
-import NoDebug.Log
 import Docs.NoMissing exposing (exposedModules, onlyExposed)
 import Docs.ReviewAtDocs
 import Docs.ReviewLinksAndSections
 import Docs.UpToDateReadmeLinks
+import NoDebug.Log
 import NoDebug.TodoOrToString
+import NoPrematureLetComputation
 import NoUnused.Dependencies
 import NoUnused.Variables
 import Review.Rule exposing (Rule)
@@ -20,4 +21,5 @@ config =
         }
     , Docs.ReviewLinksAndSections.rule
     , Docs.ReviewAtDocs.rule
+    , NoPrematureLetComputation.rule
     ]

src/Install/ClauseInCase.elm

@@ -1,15 +1,23 @@
-module Install.ClauseInCase exposing (config, makeRule, withInsertAfter, withInsertAtBeginning, withCustomErrorMessage, Config, CustomError)
+module Install.ClauseInCase exposing
+    ( Config, config, makeRule
+    , withInsertAfter, withInsertAtBeginning
+    , withCustomErrorMessage, CustomError
+    )
 
 {-| Add a clause to a case expression in a specified function
 in a specified module. For example, if you put the code below in your
 `ReviewConfig.elm` file, running `elm-review --fix` will add the clause
 `ResetCounter` to the `updateFromFrontend` function in the `Backend` module.
 
     -- code for ReviewConfig.elm:
-    Install.ClauseInCase.config "Backend" "updateFromFrontend" "ResetCounter" "( { model | counter = 0 }, broadcast (CounterNewValue 0 clientId) )"
+    Install.ClauseInCase.config
+        "Backend"
+        "updateFromFrontend"
+        "ResetCounter"
+        "( { model | counter = 0 }, broadcast (CounterNewValue 0 clientId) )"
         |> Install.ClauseInCase.makeRule
 
-    Thus we will have
+Thus we will have
 
     updateFromFrontend : SessionId -> ClientId -> ToBackend -> Model -> ( Model, Cmd BackendMsg )
     updateFromFrontend sessionId clientId msg model =
@@ -21,28 +29,14 @@ in a specified module. For example, if you put the code below in your
             ResetCounter ->
                 ( { model | counter = 0 }, broadcast (CounterNewValue 0 clientId) )
 
-    You also can add the clause after another clause of choice with the `withInsertAfter` function:
-        Install.ClauseInCase.config "Backend" "updateFromFrontend" "ResetCounter" "( { model | counter = 0 }, broadcast (CounterNewValue 0 clientId) )"
-            |> Install.ClauseInCase.withInsertAfter "CounterIncremented"
-            |> Install.ClauseInCase.makeRule
-
-    In this case we will have
-        updateFromFrontend : SessionId -> ClientId -> ToBackend -> Model -> ( Model, Cmd BackendMsg )
-        updateFromFrontend sessionId clientId msg model =
-            case msg of
-                CounterIncremented ->
-                ...
-                ResetCounter ->
-                    ( { model | counter = 0 }, broadcast (CounterNewValue 0 clientId) )
-
-                CounterDecremented ->
-                ...
-    You can also customize the error message with the `withCustomErrorMessage` function:
-        Install.ClauseInCase.config "Backend" "updateFromFrontend" "ResetCounter" "( { model | counter = 0 }, broadcast (CounterNewValue 0 clientId) )"
-            |> Install.ClauseInCase.withCustomErrorMessage "Add handler for ResetCounter" []
-            |> Install.ClauseInCase.makeRule
-
-@docs config, makeRule, withInsertAfter, withInsertAtBeginning, withCustomErrorMessage, Config, CustomError
+            ...
+
+@docs Config, config, makeRule
+
+By default, the clause will be inserted as the last clause. You can change the insertion location using the following functions:
+
+@docs withInsertAfter, withInsertAtBeginning
+@docs withCustomErrorMessage, CustomError
 
 -}
 
@@ -57,10 +51,9 @@ import List.Extra
 import Maybe.Extra
 import Review.Fix as Fix exposing (Fix)
 import Review.Rule as Rule exposing (Error, Rule)
-import String.Extra
 
 
-{-| Configuration for makeRule: add a clause to a case expression in a specified function in a specified module.
+{-| Configuration for rule: add a clause to a case expression in a specified function in a specified module.
 -}
 type Config
     = Config
@@ -87,9 +80,14 @@ type CustomError
 
 {-| Basic config to add a new clause to a case expression. If you just need to add a new clause at the end of the case, you can simply use it with the `makeRule` function like this:
 
-    Install.ClauseInCase.config "Backend" "updateFromFrontend" "ResetCounter" "( { model | counter = 0 }, broadcast (CounterNewValue 0 clientId) )"
+    Install.ClauseInCase.config
+        "Backend"
+        "updateFromFrontend"
+        "ResetCounter"
+        "( { model | counter = 0 }, broadcast (CounterNewValue 0 clientId) )"
         |> Install.ClauseInCase.makeRule
-    If you need additional configuration, check the `withInsertAfter` and `withCustomErrorMessage` functions.
+
+If you need additional configuration, check the `withInsertAfter` and `withCustomErrorMessage` functions.
 
 -}
 config : String -> String -> String -> String -> Config
@@ -104,9 +102,13 @@ config moduleName functionName clause functionCall =
         }
 
 
-{-| Create a makeRule that adds a clause to a case expression in a specified function. You can use it like this:
+{-| Create a rule that adds a clause to a case expression in a specified function. You can use it like this:
 
-    Install.ClauseInCase.config "Backend" "updateFromFrontend" "ResetCounter" "( { model | counter = 0 }, broadcast (CounterNewValue 0 clientId) )"
+    Install.ClauseInCase.config
+        "Backend"
+        "updateFromFrontend"
+        "ResetCounter"
+        "( { model | counter = 0 }, broadcast (CounterNewValue 0 clientId) )"
         |> Install.ClauseInCase.makeRule
 
 -}
@@ -151,12 +153,13 @@ declarationVisitor (Node _ declaration) moduleName functionName clause functionC
 
                 isInCorrectModule =
                     Install.Library.isInCorrectModule moduleName context
-
-                functionDeclaration : FunctionImplementation
-                functionDeclaration =
-                    Node.value function.declaration
             in
             if name == functionName && isInCorrectModule then
+                let
+                    functionDeclaration : FunctionImplementation
+                    functionDeclaration =
+                        Node.value function.declaration
+                in
                 visitFunction clause functionCall functionDeclaration.expression insertAt customError context
 
             else
@@ -197,12 +200,12 @@ visitFunction clause functionCall expressionNode insertAt customError context =
                     List.any
                         (\pattern -> Install.Library.patternToString (Node.empty pattern) == clause_)
                         (getPatterns cases_)
-
-                isClauseStringPattern =
-                    List.any isStringPattern (getPatterns allCases)
             in
             if not (findClause clause allCases) then
                 let
+                    isClauseStringPattern =
+                        List.any isStringPattern (getPatterns allCases)
+
                     rangeToInsert : Maybe ( Range, Int, Int )
                     rangeToInsert =
                         rangeToInsertClause insertAt isClauseStringPattern allCases patternMatchNode |> Just
@@ -359,7 +362,11 @@ Given the following module:
 
 To add the clause `Aspasia` after the clause `Aristotle`, you can use the following configuration:
 
-    Install.ClauseInCase.config "Philosopher" "stringToPhilosopher" "Aspasia" "Just Aspasia"
+    Install.ClauseInCase.config
+        "Philosopher"
+        "stringToPhilosopher"
+        "Aspasia"
+        "Just Aspasia"
         |> Install.ClauseInCase.withInsertAfter "Aristotle"
         |> Install.ClauseInCase.makeRule
 
@@ -393,6 +400,31 @@ withInsertAfter clauseToInsertAfter (Config config_) =
 
 
 {-| Add a clause at the beginning of the case expression.
+
+You also can add the clause after another clause of choice with the `withInsertAfter` function:
+
+    Install.ClauseInCase.config
+        "Backend"
+        "updateFromFrontend"
+        "ResetCounter"
+        "( { model | counter = 0 }, broadcast (CounterNewValue 0 clientId) )"
+        |> Install.ClauseInCase.withInsertAtBeginning
+        |> Install.ClauseInCase.makeRule
+
+In this case we will have
+
+    updateFromFrontend : SessionId -> ClientId -> ToBackend -> Model -> ( Model, Cmd BackendMsg )
+    updateFromFrontend sessionId clientId msg model =
+        case msg of
+            ResetCounter ->
+                ( { model | counter = 0 }, broadcast (CounterNewValue 0 clientId) )
+
+            CounterIncremented ->
+            ...
+
+            CounterDecremented ->
+            ...
+
 -}
 withInsertAtBeginning : Config -> Config
 withInsertAtBeginning (Config config_) =
@@ -402,7 +434,16 @@ withInsertAtBeginning (Config config_) =
         }
 
 
-{-| Customize the error message that will be displayed when running `elm-review --fix` or `elm-review --fix-all`
+{-| Customize the error message that will be displayed when running `elm-review --fix` or `elm-review --fix-all`.
+
+    Install.ClauseInCase.config
+        "Backend"
+        "updateFromFrontend"
+        "ResetCounter"
+        "( { model | counter = 0 }, broadcast (CounterNewValue 0 clientId) )"
+        |> Install.ClauseInCase.withCustomErrorMessage "Add handler for ResetCounter" []
+        |> Install.ClauseInCase.makeRule
+
 -}
 withCustomErrorMessage : String -> List String -> Config -> Config
 withCustomErrorMessage errorMessage details (Config config_) =

src/Install/ElementToList.elm

@@ -21,7 +21,10 @@ import String.Extra
 
 For example, the rule
 
-    Install.ElementToList.makeRule "User" "userTypes" [ "Admin", "SystemAdmin" ]
+    Install.ElementToList.makeRule
+        "User"
+        "userTypes"
+        [ "Admin", "SystemAdmin" ]
 
 results in the following fix for function `User.userTypes`:
 

src/Install/FieldInTypeAlias.elm

@@ -44,14 +44,16 @@ import Set.Extra
 
 After running the rule with the following code:
 
-    Install.FieldInTypeAlias.makeRule "Types" "FrontendModel" ["clientName: String", "quot: String"]
+    Install.FieldInTypeAlias.makeRule "Types" "FrontendModel" [ "clientName: String", "quot: String" ]
 
-        type alias FrontendModel =
-            { counter : Int
-            , clientId : String
-            , clientName : String
-            , quot : String
-            }
+we will have
+
+    type alias FrontendModel =
+        { counter : Int
+        , clientId : String
+        , clientName : String
+        , quot : String
+        }
 
 -}
 makeRule : String -> String -> List String -> Rule

src/Install/Function/InsertFunction.elm

@@ -37,7 +37,7 @@ import Review.ModuleNameLookupTable exposing (ModuleNameLookupTable)
 import Review.Rule as Rule exposing (Error, Rule)
 
 
-{-| Configuration for makeRule: add a function in a specified module if it does not already exist.
+{-| Configuration for rule: add a function in a specified module if it does not already exist.
 -}
 type Config
     = Config
@@ -71,12 +71,12 @@ withInsertAfter previousDeclaration (Config config_) =
 {-| Initialize the configuration for the rule.
 -}
 config : String -> String -> String -> Config
-config moduleNaeme functionName functionImplementation =
+config moduleName functionName functionImplementation =
     Config
-        { moduleName = moduleNaeme
+        { moduleName = moduleName
         , functionName = functionName
         , functionImplementation = functionImplementation
-        , theFunctionNodeExpression = Install.Library.maybeNodeExpressionFromString { moduleName = String.split "." moduleNaeme } functionImplementation
+        , theFunctionNodeExpression = Install.Library.maybeNodeExpressionFromString { moduleName = String.split "." moduleName } functionImplementation
         , customErrorMessage = CustomError { message = "Add function \"" ++ functionName ++ "\".", details = [ "" ] }
         , insertAt = AtEnd
         }
@@ -119,24 +119,23 @@ declarationVisitor context (Config config_) declaration =
     let
         declarationName =
             Install.Library.getDeclarationName declaration
-
-        contextWithLastDeclarationRange =
-            case config_.insertAt of
-                After previousDeclaration ->
-                    if Install.Library.getDeclarationName declaration == previousDeclaration then
-                        { context | lastDeclarationRange = Node.range declaration }
-
-                    else
-                        context
-
-                AtEnd ->
-                    { context | lastDeclarationRange = Node.range declaration }
     in
     if declarationName == config_.functionName then
         ( [], { context | appliedFix = True } )
 
     else
-        ( [], contextWithLastDeclarationRange )
+        ( []
+        , case config_.insertAt of
+            After previousDeclaration ->
+                if Install.Library.getDeclarationName declaration == previousDeclaration then
+                    { context | lastDeclarationRange = Node.range declaration }
+
+                else
+                    context
+
+            AtEnd ->
+                { context | lastDeclarationRange = Node.range declaration }
+        )
 
 
 finalEvaluation : Config -> Context -> List (Rule.Error {})