From 7dfe340019da2fc7e00c5d5276a4b140766654dd Mon Sep 17 00:00:00 2001 From: Ky Bishop Date: Thu, 13 Feb 2025 14:18:38 -0500 Subject: [PATCH] fixups and docs --- docs/comment_directives.md | 59 ++++++++++++++++++++++++ lib/style/comment_directives.ex | 7 +-- mix.exs | 5 ++- test/style/comment_directives_test.exs | 62 +++++++++++++------------- 4 files changed, 97 insertions(+), 36 deletions(-) create mode 100644 docs/comment_directives.md diff --git a/docs/comment_directives.md b/docs/comment_directives.md new file mode 100644 index 0000000..fb41dd3 --- /dev/null +++ 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 index 500b9eb..25ab6f4 100644 --- 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 index ec653d7..93cca53 100644 --- 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 index 448de73..6230cf1 100644 --- 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