Review.Documentation.CodeSnippet

Checks your small code examples in the readme, module headers and declaration comments for valid syntax, matching types and correctness by generating tests from these code snippets.

import Review.Documentation.CodeSnippet


config =
    [ Review.Documentation.CodeSnippet.check
    ]

check : Rule

Rule to generate tests from your documentation examples (readme, module header, declaration comment) and also to report syntax errors for these code snippets. There are two kinds of checks:

value checks

module Dict.Extra exposing (keySet)


{-| `Dict.keys` but returning a `Set` instead of a `List`.


    import Dict
    import Set


    type Letter
        = A
        | B
        | C


    Dict.fromList [ ( 0, A ), ( 1, B ), ( 2, C ) ]
        |> Dict.Extra.keySet
    --> Set.fromList [ 0, 1, 2 ]


    -- or
    Dict.fromList [ ( 0, A ), ( 1, B ), ( 2, C ) ]
        |> Dict.Extra.keySet
    -->
    Set.fromList
        [ 0
        , 1
        , 2
        ]


    -- or
    Dict.fromList [ ( 0, A ), ( 1, B ), ( 2, C ) ]
        |> Dict.Extra.keySet
    --> Set.fromList
    -->     [ 0
    -->     , 1
    -->     , 2
    -->     ]


-}
keySet = ...

This verifies that the actual value of the expression before --> is the same as the expected value after -->.

type checks

module Codec exposing (Codec, record, field, recordFinish, signedInt)


{-| Start creating a codec for a record.


    import Codec exposing (Codec)


    type alias Point =
        { x : Int, y : Int }


    Codec.record (\x y -> { x = x, y = y })
        |> Codec.field .x Codec.signedInt
        |> Codec.field .y Codec.signedInt
        |> Codec.recordFinish
    --: Codec Point
-}
record = ...

Note that because you use the type Codec unqualified in your check, you have to explicitly import it. (This is different from elm-verify-examples which implicitly exposes all local module members. In case you want to simulate that behaviour for legacy reasons, use checkImplicitlyImportingEverythingFromCurrentModule)

important The rule will only report syntax and type errors if your code snippet contains at least one of these two checks, so replace

{-| ...


    myResult : Cmd Int
    myResult =
        Ok 3 |> Cmd.Extra.fromResult


-}

with

{-| ...


    Ok 3 |> Cmd.Extra.fromResult
    --: Cmd Int


-}

Both checks will be run on all modules and the readme. If you want to disable this for e.g. generated or vendored code, use Review.Rule.ignoreErrorsForDirectories

checkImplicitlyImportingEverythingFromCurrentModule : Rule

A version of check primarily intended to offer compatibility with elm-verify-examples for legacy codebases.

It will implicitly interpret

module CurrentModule exposing (doSomething)


{-| Does something


    doSomething --> "something was done"


-}
doSomething

module CurrentModule exposing (doSomething)


{-| Does something


    import CurrentModule exposing (..)


    doSomething --> "something was done"


-}
doSomething

History: This was the previous behaviour of the rule in version 1. Shadowing issues initiated the search for better alternatives. Requiring explicit imports for exposing members of the current module turned out to make the snippets easier to understand, easier to copy into your code and less error prone. See above linked issue to see considered alternatives or suggest one yourself.

Modules