fixups and docs

smartrent · Feb 13, 2025 · 7dfe340 · 7dfe340
1 parent 9dd0402
commit 7dfe340
Show file tree

Hide file tree

Showing 4 changed files with 97 additions and 36 deletions.
diff --git a/docs/comment_directives.md b/docs/comment_directives.md
@@ -0,0 +1,59 @@
+# Comment Directives
+
+## Maintain static list order via `# quokka:sort`
+
+Quokka can keep static values sorted for your team as part of its formatting pass. To instruct it to do so, replace any `# Please keep this list sorted!` notes you wrote to your teammates with `# quokka:sort`.
+
+#### Examples
+
+```elixir
+# quokka:sort
+[:c, :a, :b]
+
+# quokka:sort
+~w(a list of words)
+
+# quokka:sort
+@country_codes ~w(
+  en_US
+  po_PO
+  fr_CA
+  ja_JP
+)
+
+# quokka:sort
+a_var =
+  [
+    Modules,
+    In,
+    A,
+    List
+  ]
+```
+
+Would yield:
+
+```elixir
+# quokka:sort
+[:a, :b, :c]
+
+# quokka:sort
+~w(a list of words)
+
+# quokka:sort
+@country_codes ~w(
+  en_US
+  fr_CA
+  ja_JP
+  po_PO
+)
+
+# quokka:sort
+a_var =
+  [
+    A,
+    In,
+    List,
+    Modules
+  ]
+```
diff --git a/lib/style/comment_directives.ex b/lib/style/comment_directives.ex
@@ -1,4 +1,5 @@
 # Copyright 2024 Adobe. All rights reserved.
+# Copyright 2025 SmartRent. All rights reserved.
 # This file is licensed to you under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License. You may obtain a copy
 # of the License at http://www.apache.org/licenses/LICENSE-2.0
@@ -10,9 +11,9 @@
 
 defmodule Quokka.Style.CommentDirectives do
   @moduledoc """
-  Leave a comment for Styler asking it to maintain code in a certain way.
+  Leave a comment for Quokka asking it to maintain code in a certain way.
 
-  `# styler:sort` maintains sorting of wordlists (by string comparison) and lists (string comparison of code representation)
+  `# quokka:sort` maintains sorting of wordlists (by string comparison) and lists (string comparison of code representation)
   """
 
   @behaviour Quokka.Style
@@ -23,7 +24,7 @@ defmodule Quokka.Style.CommentDirectives do
   def run(zipper, ctx) do
     {zipper, comments} =
       ctx.comments
-      |> Enum.filter(&(&1.text == "# styler:sort"))
+      |> Enum.filter(&(&1.text == "# quokka:sort"))
       |> Enum.map(& &1.line)
       |> Enum.reduce({zipper, ctx.comments}, fn line, {zipper, comments} ->
         found =

diff --git a/mix.exs b/mix.exs
@@ -67,11 +67,12 @@ defmodule Quokka.MixProject do
       extra_section: "Docs",
       extras: [
         "CHANGELOG.md": [title: "Changelog"],
-        "docs/styles.md": [title: "Basic Styles"],
-        "docs/pipes.md": [title: "Pipe Chains"],
+        "docs/comment_directives.md": [title: "Comment Directives (quokka:sort, ...)"],
         "docs/control_flow_macros.md": [title: "Control Flow Macros (if, case, ...)"],
         "docs/mix_configs.md": [title: "Mix Configs (config/config.exs, ...)"],
         "docs/module_directives.md": [title: "Module Directives (use, alias, ...)"],
+        "docs/pipes.md": [title: "Pipe Chains"],
+        "docs/styles.md": [title: "Basic Styles"],
         "README.md": [title: "Quokka"],
         LICENSE: [title: "License"]
       ]

diff --git a/test/style/comment_directives_test.exs b/test/style/comment_directives_test.exs
@@ -20,7 +20,7 @@ defmodule Quokka.Style.CommentDirectivesTest do
     test "sorts lists of atoms" do
       assert_style(
         """
-        # styler:sort
+        # quokka:sort
         [
           :c,
           :b,
@@ -29,7 +29,7 @@ defmodule Quokka.Style.CommentDirectivesTest do
         ]
         """,
         """
-        # styler:sort
+        # quokka:sort
         [
           :a,
           :b,
@@ -43,7 +43,7 @@ defmodule Quokka.Style.CommentDirectivesTest do
     test "sort keywordy things" do
       assert_style(
         """
-        # styler:sort
+        # quokka:sort
         [
           c: 2,
           b: 3,
@@ -52,7 +52,7 @@ defmodule Quokka.Style.CommentDirectivesTest do
         ]
         """,
         """
-        # styler:sort
+        # quokka:sort
         [
           a: 4,
           b: 3,
@@ -64,7 +64,7 @@ defmodule Quokka.Style.CommentDirectivesTest do
 
       assert_style(
         """
-        # styler:sort
+        # quokka:sort
         %{
           c: 2,
           b: 3,
@@ -73,7 +73,7 @@ defmodule Quokka.Style.CommentDirectivesTest do
         }
         """,
         """
-        # styler:sort
+        # quokka:sort
         %{
           a: 4,
           b: 3,
@@ -85,7 +85,7 @@ defmodule Quokka.Style.CommentDirectivesTest do
 
       assert_style(
         """
-        # styler:sort
+        # quokka:sort
         %Struct{
           c: 2,
           b: 3,
@@ -94,7 +94,7 @@ defmodule Quokka.Style.CommentDirectivesTest do
         }
         """,
         """
-        # styler:sort
+        # quokka:sort
         %Struct{
           a: 4,
           b: 3,
@@ -106,18 +106,18 @@ defmodule Quokka.Style.CommentDirectivesTest do
 
       assert_style(
         """
-        # styler:sort
+        # quokka:sort
         defstruct c: 2, b: 3, a: 4, d: 1
         """,
         """
-        # styler:sort
+        # quokka:sort
         defstruct a: 4, b: 3, c: 2, d: 1
         """
       )
 
       assert_style(
         """
-        # styler:sort
+        # quokka:sort
         defstruct [
           :repo,
           :query,
@@ -128,7 +128,7 @@ defmodule Quokka.Style.CommentDirectivesTest do
         ]
         """,
         """
-        # styler:sort
+        # quokka:sort
         defstruct [
           :chunk_size,
           :cursor,
@@ -146,7 +146,7 @@ defmodule Quokka.Style.CommentDirectivesTest do
         """
         %{
           key:
-          # styler:sort
+          # quokka:sort
           [
             3,
             2,
@@ -156,7 +156,7 @@ defmodule Quokka.Style.CommentDirectivesTest do
         """,
         """
         %{
-          # styler:sort
+          # quokka:sort
           key: [
             1,
             2,
@@ -169,7 +169,7 @@ defmodule Quokka.Style.CommentDirectivesTest do
       assert_style(
         """
         %{
-          # styler:sort
+          # quokka:sort
           key: [
             3,
             2,
@@ -179,7 +179,7 @@ defmodule Quokka.Style.CommentDirectivesTest do
         """,
         """
         %{
-          # styler:sort
+          # quokka:sort
           key: [
             1,
             2,
@@ -191,11 +191,11 @@ defmodule Quokka.Style.CommentDirectivesTest do
     end
 
     test "sorts sigils" do
-      assert_style("# styler:sort\n~w|c a b|", "# styler:sort\n~w|a b c|")
+      assert_style("# quokka:sort\n~w|c a b|", "# quokka:sort\n~w|a b c|")
 
       assert_style(
         """
-        # styler:sort
+        # quokka:sort
         ~w(
           a
           long
@@ -206,7 +206,7 @@ defmodule Quokka.Style.CommentDirectivesTest do
         )
         """,
         """
-        # styler:sort
+        # quokka:sort
         ~w(
           a
           list
@@ -222,7 +222,7 @@ defmodule Quokka.Style.CommentDirectivesTest do
     test "assignments" do
       assert_style(
         """
-        # styler:sort
+        # quokka:sort
         my_var =
           ~w(
             a
@@ -234,7 +234,7 @@ defmodule Quokka.Style.CommentDirectivesTest do
           )
         """,
         """
-        # styler:sort
+        # quokka:sort
         my_var =
           ~w(
             a
@@ -251,7 +251,7 @@ defmodule Quokka.Style.CommentDirectivesTest do
         """
         defmodule M do
           @moduledoc false
-          # styler:sort
+          # quokka:sort
           @attr ~w(
               a
               long
@@ -265,7 +265,7 @@ defmodule Quokka.Style.CommentDirectivesTest do
         """
         defmodule M do
           @moduledoc false
-          # styler:sort
+          # quokka:sort
           @attr ~w(
               a
               list
@@ -282,7 +282,7 @@ defmodule Quokka.Style.CommentDirectivesTest do
     test "doesnt affect downstream nodes" do
       assert_style(
         """
-        # styler:sort
+        # quokka:sort
         [:c, :a, :b]
 
         @country_codes ~w(
@@ -293,7 +293,7 @@ defmodule Quokka.Style.CommentDirectivesTest do
         )
         """,
         """
-        # styler:sort
+        # quokka:sort
         [:a, :b, :c]
 
         @country_codes ~w(
@@ -311,7 +311,7 @@ defmodule Quokka.Style.CommentDirectivesTest do
       # decided the easiest way to handle this is to just use string representation for meow
       assert_style(
         """
-        # styler:sort
+        # quokka:sort
         [
           {:styler, github: "adobe/elixir-styler"},
           {:ash, "~> 3.0"},
@@ -321,7 +321,7 @@ defmodule Quokka.Style.CommentDirectivesTest do
         ]
         """,
         """
-        # styler:sort
+        # quokka:sort
         [
           {:ash, "~> 3.0"},
           {:fluxon, "~> 1.0.0", repo: :fluxon},
@@ -336,7 +336,7 @@ defmodule Quokka.Style.CommentDirectivesTest do
     test "nodes within a do end block" do
       assert_style(
         """
-        # styler:sort
+        # quokka:sort
         my_macro "some arg" do
           another_macro :q
           # w
@@ -350,7 +350,7 @@ defmodule Quokka.Style.CommentDirectivesTest do
         end
         """,
         """
-        # styler:sort
+        # quokka:sort
         my_macro "some arg" do
           another_macro(:e)
           another_macro(:q)
@@ -370,7 +370,7 @@ defmodule Quokka.Style.CommentDirectivesTest do
       assert_style(
         """
         # pre-amble comment
-        # styler:sort
+        # quokka:sort
         [
           {:phoenix, "~> 1.7"},
           # hackney comment
@@ -393,7 +393,7 @@ defmodule Quokka.Style.CommentDirectivesTest do
         """,
         """
         # pre-amble comment
-        # styler:sort
+        # quokka:sort
         [
           {:credo, "~> 1.7", only: [:dev, :test], runtime: false},
           # ecto