{"id":15059356,"url":"https://github.com/lue-bird/elm-review-documentation-code-snippet","last_synced_at":"2026-03-01T19:31:00.466Z","repository":{"id":225250036,"uuid":"764832371","full_name":"lue-bird/elm-review-documentation-code-snippet","owner":"lue-bird","description":"verify code examples by generating tests","archived":false,"fork":false,"pushed_at":"2024-06-28T11:06:10.000Z","size":218,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-13T12:00:03.643Z","etag":null,"topics":["documentation","elm","elm-review","test","verify-examples"],"latest_commit_sha":null,"homepage":"https://dark.elm.dmy.fr/packages/lue-bird/elm-review-documentation-code-snippet/latest","language":"Elm","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lue-bird.png","metadata":{"files":{"readme":"README.md","changelog":"changes.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-02-28T19:43:18.000Z","updated_at":"2024-06-28T11:06:14.000Z","dependencies_parsed_at":"2024-03-27T19:29:54.304Z","dependency_job_id":"669f832b-a584-4634-950b-591820d30ce7","html_url":"https://github.com/lue-bird/elm-review-documentation-code-snippet","commit_stats":null,"previous_names":["lue-bird/elm-review-documentation-code-snippet"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/lue-bird/elm-review-documentation-code-snippet","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lue-bird%2Felm-review-documentation-code-snippet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lue-bird%2Felm-review-documentation-code-snippet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lue-bird%2Felm-review-documentation-code-snippet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lue-bird%2Felm-review-documentation-code-snippet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lue-bird","download_url":"https://codeload.github.com/lue-bird/elm-review-documentation-code-snippet/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lue-bird%2Felm-review-documentation-code-snippet/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29981413,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-01T16:35:47.903Z","status":"ssl_error","status_checked_at":"2026-03-01T16:35:44.899Z","response_time":124,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["documentation","elm","elm-review","test","verify-examples"],"created_at":"2024-09-24T22:42:19.338Z","updated_at":"2026-03-01T19:31:00.041Z","avatar_url":"https://github.com/lue-bird.png","language":"Elm","funding_links":[],"categories":[],"sub_categories":[],"readme":"[🔧 `Review.Documentation.CodeSnippet.check`](https://package.elm-lang.org/packages/lue-bird/elm-review-documentation-example/1.1.3/Review-Documentation-CodeSnippet#check \"provides fixes\") checks your small code examples in the readme, module headers and declaration comments for valid syntax, matching types and correctness.\n\nTo check this, it generates tests from these code snippets\n(If you know [`elm-verify-examples`](https://github.com/stoeffel/elm-verify-examples), you also know how this works. This rule has only a few extras like checking for types or actually getting errors for invalid syntax.)\n```elm\nmodule Dict.Extra exposing (keySet)\n\n{-| `Dict.keys` but returning a `Set` instead of a `List`.\n\n    import Dict\n    import Set\n\n    Dict.fromList [ ( 0, \"A\" ), ( 1, \"B\" ), ( 2, \"C\" ) ]\n        |\u003e Dict.Extra.keySet\n    --\u003e Set.fromList [ 0, 1, 2 ]\n\n-}\nkeySet = ...\n```\nwhich will generate a test with\n```elm\nDict.fromList [ ( 0, \"A\" ), ( 1, \"B\" ), ( 2, \"C\" ) ]\n    |\u003e Dict.Extra.keySet\n    |\u003e Expect.equal (Set.fromList [ 0, 1, 2 ])\n```\n\n## why?\n\nFinding broken or incorrect examples in the documentation is confusing and frustrating to new users.\nAt the same time, these examples quickly get out of sync with your API.\nNow, how do you find all the places where things changed for your examples?\nThe compiler certainly doesn't check them which makes it easy to miss some\n\n## setup\n\n  - ```noformatingples\n    elm install lue-bird/elm-review-documentation-code-snippet\n    ```\n    then add the rule to your `review/src/ReviewConfig.elm`\n    ```elm\n    import Review.Rule\n    import Review.Documentation.CodeSnippet\n\n    config : List Review.Rule.Rule\n    config =\n        [ Review.Documentation.CodeSnippet.check\n        ]\n    ```\n    or if you don't want to install it, yet\n    ```noformatingples\n    elm-review --template lue-bird/elm-review-documentation-code-snippet/example\n    ```\n  - add a minimal `tests/DocumentationCodeSnippetTest.elm` which the rule can overwrite. Something like\n    ```elm\n    module DocumentationCodeSnippetTest exposing (tests)\n    tests =\n        tests\n    ```\n    You can add this file to `.gitignore`.\n\nI suggest running it in the background\n```noformatingples\nelm-review --rules Review.Documentation.CodeSnippet --watch --fix-all-without-prompt\n```\nwhile from time to time keeping an eye on possible reported syntax errors and failing/non-compiling generated tests.\n\n## thanks\n  - Christoph Hermann (stoeffel) for [elm-verify-examples](https://github.com/stoeffel/elm-verify-examples)\n    which established the core ideas and syntax in a nice command line tool\n  - dillonkearns for [elm-markdown](https://dark.elm.dmy.fr/packages/dillonkearns/elm-markdown/latest/) of which parts are used as a base for finding code blocks\n  - Rupert Smith for [elm-syntax-dsl](https://dark.elm.dmy.fr/packages/the-sett/elm-syntax-dsl/latest) which can pretty print a whole elm file and is compatible with `elm-syntax`\n  - miniBill for [elm-fast-dict](https://dark.elm.dmy.fr/packages/miniBill/elm-fast-dict/latest)\n\n## what could we add in the future?\n\n  - fuzzy check syntax. Something like\n    ```elm\n    --* xs is list unit\n    List.take 3 xs |\u003e List.length\n    --\u003e Basics.maximum 3 (xs |\u003e List.length)\n\n    --* xs, ys is list unit\n    List.map2 Tuple.pair xs ys |\u003e List.length\n    --\u003e Basics.minimum (xs |\u003e List.length) (ys |\u003e List.length)\n    ```\n    where `list unit` is interpreted as `Fuzz.list (Fuzz.constant ())`\n  - compare imports with used module names and automatically add missing imports as a fix\n  - ✨ your idea\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flue-bird%2Felm-review-documentation-code-snippet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flue-bird%2Felm-review-documentation-code-snippet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flue-bird%2Felm-review-documentation-code-snippet/lists"}