Add Elm.docs and revise previous notion of how to create docs.

mdgriffith · Aug 25, 2024 · 864f9ca · 864f9ca
1 parent c7d473e
commit 864f9ca
Show file tree

Hide file tree

Showing 6 changed files with 95 additions and 90 deletions.
diff --git a/src/Elm.elm b/src/Elm.elm
@@ -8,7 +8,7 @@ module Elm exposing
     , record, get, updateRecord
     , ifThen
     , Declaration
-    , comment, declaration
+    , comment, docs, declaration
     , withDocumentation, group
     , expose, exposeConstructor
     , fileWith
@@ -59,7 +59,7 @@ A `Declaration` is anything that is at the "top level" of your file, meaning all
 
 @docs Declaration
 
-@docs comment, declaration
+@docs comment, docs, declaration
 
 @docs withDocumentation, group
 
@@ -2066,32 +2066,30 @@ exposeConstructor =
     Compiler.exposeConstructor
 
 
-{-| Group declarations under a title in the doc comment at the top of the generated module.
+{-| Group declarations in a module.
 
-This will also add a `@docs` tag to the module doc comment for any exposed functions in the group.
+This will add a `@docs` tag to the module doc comment for any exposed functions in the group.
 
     Elm.group
-        { title = "MyGroup"
-        , docs = "This is a group of functions that do things"
-        }
-        [ myFunction, myOtherFunction ]
+        [ myFunction
+        , myOtherFunction
+        ]
 
 Will create the following module doc comment:
 
-    ## My Group
+    @docs myFunction, myOtherFunction
 
-    This is a group of functions that do things
+-}
+group : List Declaration -> Declaration
+group decls =
+    Compiler.Group decls
 
-    @docs myFunction, myOtherFunction
 
+{-| This will include some markdown in the module doc comment.
 -}
-group : { title : String, docs : String } -> List Declaration -> Declaration
-group options decls =
-    Compiler.Group
-        { title = options.title
-        , docs = options.docs
-        , decls = decls
-        }
+docs : String -> Declaration
+docs =
+    Compiler.ModuleDocs
 
 
 {-|

diff --git a/src/Elm/Declare.elm b/src/Elm/Declare.elm
@@ -858,8 +858,4 @@ withSubmodule submod mod =
 -}
 include : Module val -> Elm.Declaration
 include mod =
-    Compiler.Group
-        { title = mod.title
-        , docs = mod.docs
-        , decls = mod.declarations
-        }
+    Compiler.Group mod.declarations
diff --git a/src/Elm/ToString.elm b/src/Elm/ToString.elm
@@ -115,7 +115,17 @@ declarationWith :
 declarationWith options decl =
     case decl of
         Compiler.Group group ->
-            List.concatMap (declarationWith options) group.decls
+            List.concatMap (declarationWith options) group
+
+        Compiler.ModuleDocs docs ->
+            [ { imports =
+                    ""
+              , body = ""
+              , docs = docs
+              , signature =
+                    ""
+              }
+            ]
 
         Compiler.Declaration { imports, docs, toBody } ->
             let

diff --git a/src/Internal/Compiler.elm b/src/Internal/Compiler.elm
@@ -96,12 +96,9 @@ getTypeModule (Annotation annotation) =
 type Declaration
     = Declaration DeclarationDetails
     | Comment String
+    | ModuleDocs String
     | Block String
-    | Group
-        { title : String
-        , docs : String
-        , decls : List Declaration
-        }
+    | Group (List Declaration)
 
 
 type RenderedDeclaration
@@ -646,6 +643,9 @@ documentation rawDoc decl =
             Block _ ->
                 decl
 
+            ModuleDocs _ ->
+                decl
+
             Declaration details ->
                 Declaration
                     { details
@@ -658,12 +658,8 @@ documentation rawDoc decl =
                                     Just (doc ++ "\n\n" ++ existing)
                     }
 
-            Group group ->
-                Group
-                    { group
-                        | decls =
-                            List.map (documentation doc) group.decls
-                    }
+            Group groupDecls ->
+                Group (List.map (documentation doc) groupDecls)
 
 
 {-| -}
@@ -676,6 +672,9 @@ expose decl =
         Block _ ->
             decl
 
+        ModuleDocs _ ->
+            decl
+
         Declaration details ->
             Declaration
                 { details
@@ -689,7 +688,7 @@ expose decl =
                 }
 
         Group group ->
-            Group { group | decls = List.map expose group.decls }
+            Group (List.map expose group)
 
 
 {-| -}
@@ -702,6 +701,9 @@ exposeConstructor decl =
         Block _ ->
             decl
 
+        ModuleDocs _ ->
+            decl
+
         Declaration details ->
             Declaration
                 { details
@@ -715,7 +717,7 @@ exposeConstructor decl =
                 }
 
         Group group ->
-            Group { group | decls = List.map exposeConstructor group.decls }
+            Group (List.map exposeConstructor group)
 
 
 type alias Module =

diff --git a/src/Internal/Render.elm b/src/Internal/Render.elm
@@ -49,12 +49,11 @@ getExposedGroups decl groups =
                 Compiler.Exposed _ ->
                     Exposed decDetails.name :: groups
 
-        Compiler.Group group ->
-            ExposedGroup
-                { title = group.title
-                , docs = group.docs
-                , items = List.foldl getExposedGroups [] group.decls
-                }
+        Compiler.ModuleDocs docs ->
+            ModuleDocs docs :: groups
+
+        Compiler.Group groupDecls ->
+            ExposedGroup (List.foldl getExposedGroups [] groupDecls)
                 :: groups
 
         _ ->
@@ -86,6 +85,9 @@ renderDecls fileDetails decl gathered =
         Compiler.Block block ->
             { gathered | declarations = Compiler.RenderedBlock block :: gathered.declarations }
 
+        Compiler.ModuleDocs _ ->
+            gathered
+
         Compiler.Declaration decDetails ->
             let
                 result :
@@ -122,19 +124,16 @@ renderDecls fileDetails decl gathered =
                         warn :: gathered.warnings
             }
 
-        Compiler.Group group ->
+        Compiler.Group groupDecls ->
             List.foldl (renderDecls fileDetails)
                 gathered
-                group.decls
+                groupDecls
 
 
 type ExposedGroup
     = Exposed String
-    | ExposedGroup
-        { title : String
-        , docs : String
-        , items : List ExposedGroup
-        }
+    | ModuleDocs String
+    | ExposedGroup (List ExposedGroup)
 
 
 {-| -}
@@ -220,7 +219,7 @@ render initialDocs fileDetails =
                             (Internal.Comments.addPart
                                 Internal.Comments.emptyComment
                                 (Internal.Comments.Markdown
-                                    (docCommentString ++ "\n")
+                                    ("\n" ++ docCommentString ++ "\n")
                                 )
                             )
                 }
@@ -253,13 +252,29 @@ exposedGroupToMarkdown docMode groups mode rendered =
                 RenderingDocsLine ->
                     rendered
 
+        (ModuleDocs docs) :: rest ->
+            case mode of
+                Normal ->
+                    let
+                        separator =
+                            if String.isEmpty rendered then
+                                ""
+
+                            else
+                                "\n\n"
+                    in
+                    exposedGroupToMarkdown docMode rest mode (rendered ++ separator ++ docs)
+
+                RenderingDocsLine ->
+                    exposedGroupToMarkdown docMode rest mode (rendered ++ "\n\n" ++ docs)
+
         (Exposed exposedName) :: rest ->
             case docMode of
                 Everything ->
                     case mode of
                         Normal ->
                             if String.isEmpty rendered then
-                                exposedGroupToMarkdown docMode rest RenderingDocsLine ("\n@docs " ++ exposedName)
+                                exposedGroupToMarkdown docMode rest RenderingDocsLine ("@docs " ++ exposedName)
 
                             else
                                 exposedGroupToMarkdown docMode rest RenderingDocsLine (rendered ++ "\n\n@docs " ++ exposedName)
@@ -270,47 +285,20 @@ exposedGroupToMarkdown docMode groups mode rendered =
                 OnlyGroups ->
                     exposedGroupToMarkdown docMode rest mode rendered
 
-        (ExposedGroup group) :: rest ->
+        (ExposedGroup groupDecls) :: rest ->
             let
                 renderedSection =
                     exposedGroupToMarkdown docMode
-                        (List.reverse group.items)
+                        (List.reverse groupDecls)
                         Normal
-                        (let
-                            hasTitle =
-                                not (String.isEmpty group.title)
-
-                            title =
-                                if hasTitle then
-                                    "## " ++ group.title
-
-                                else
-                                    ""
-
-                            docsString =
-                                if String.isEmpty group.docs then
-                                    ""
-
-                                else if hasTitle then
-                                    "\n\n" ++ group.docs
-
-                                else
-                                    group.docs
-                         in
-                         title ++ docsString
-                        )
+                        ""
 
                 separator =
                     if String.isEmpty rendered then
-                        "\n"
+                        ""
 
                     else
-                        case mode of
-                            Normal ->
-                                "\n\n"
-
-                            RenderingDocsLine ->
-                                "\n\n"
+                        "\n\n"
             in
             exposedGroupToMarkdown docMode
                 rest

diff --git a/tests/File.elm b/tests/File.elm
@@ -116,8 +116,10 @@ grouping =
                     (Elm.file [ "Test" ]
                         [ placeholder "one"
                         , placeholder "two"
-                        , Elm.group { title = "My group", docs = "Here's how to use it" }
-                            [ placeholder "three"
+                        , Elm.group
+                            [ Elm.docs "## My group"
+                            , Elm.docs "Here's how to use it"
+                            , placeholder "three"
                             , placeholder "four"
                             ]
                         , placeholder "five"
@@ -170,18 +172,22 @@ six arg =
                         [ placeholder "one"
                             |> Elm.expose
                         , placeholder "two"
-                        , Elm.group { title = "My group", docs = "Here's how to use it" }
-                            [ placeholder "three"
+                        , Elm.group
+                            [ Elm.docs "## My group"
+                            , Elm.docs "Here's how to use it"
+                            , placeholder "three"
                             , placeholder "four"
                                 |> Elm.expose
+                            , placeholder "fourPointFive"
+                                |> Elm.expose
                             ]
                         , placeholder "five"
                             |> Elm.expose
                         , placeholder "six"
                             |> Elm.expose
                         ]
                     )
-                    """module Test exposing (five, four, one, six)
+                    """module Test exposing (five, four, fourPointFive, one, six)
 
 {-|
 @docs one
@@ -190,7 +196,7 @@ six arg =
 
 Here's how to use it
 
-@docs four
+@docs four, fourPointFive
 
 @docs five, six
 -}
@@ -217,6 +223,11 @@ four arg =
     arg
 
 
+fourPointFive : arg -> arg
+fourPointFive arg =
+    arg
+
+
 five : arg -> arg
 five arg =
     arg