diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index ce7b2dbb3..3694e17de 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -65,7 +65,7 @@ jobs: file_pattern: formatters elixir: - runs-on: ubuntu-latest + runs-on: ${{ matrix.os }} strategy: fail-fast: false matrix: @@ -73,17 +73,22 @@ jobs: # Test very old Elixir and Erlang - elixir: "1.15" otp: "25" + os: ubuntu-24.04 # Test Erlang without -doc attribute support - elixir: "1.16" otp: "26" + os: ubuntu-24.04 # Test with initial Erlang doc attribute support - elixir: "1.17" otp: "27" + os: ubuntu-latest - elixir: "1.18" otp: "27" + os: ubuntu-latest # Test with latest Elixir and Erlang versions - elixir: "1.19" otp: "29" + os: ubuntu-latest lint: true steps: - uses: actions/checkout@v3 diff --git a/lib/ex_doc/doc_ast.ex b/lib/ex_doc/doc_ast.ex index 7f7cbbcdf..9439e8b1b 100644 --- a/lib/ex_doc/doc_ast.ex +++ b/lib/ex_doc/doc_ast.ex @@ -186,6 +186,70 @@ defmodule ExDoc.DocAST do end) end + @doc """ + Merges adjacent inline code and linked-code nodes into one code node. + """ + def merge_code_segments(ast) when is_list(ast) do + ast + |> Enum.map(&merge_code_segments/1) + |> Enum.reduce([], &merge_code_segment/2) + |> Enum.reverse() + end + + def merge_code_segments({:pre, _, _, _} = ast), do: ast + + def merge_code_segments({tag, attrs, inner, meta}) do + {tag, attrs, merge_code_segments(inner), meta} + end + + def merge_code_segments(ast), do: ast + + defp merge_code_segment(right, [separator, left | rest]) when is_binary(separator) do + with "" <- String.trim_leading(separator), + false <- String.contains?(separator, ["\n", "\r"]), + {left_attrs, left_inner, left_meta} <- code_segment(left), + {right_attrs, right_inner, _right_meta} <- code_segment(right), + {:ok, attrs} <- merge_code_attrs(left_attrs, right_attrs) do + [{:code, attrs, left_inner ++ [separator] ++ right_inner, left_meta} | rest] + else + _ -> [right, separator, left | rest] + end + end + + defp merge_code_segment(right, [left | rest]) do + with {left_attrs, left_inner, left_meta} <- code_segment(left), + {right_attrs, right_inner, _right_meta} <- code_segment(right), + {:ok, attrs} <- merge_code_attrs(left_attrs, right_attrs) do + [{:code, attrs, left_inner ++ code_joiner(left_inner) ++ right_inner, left_meta} | rest] + else + _ -> [right, left | rest] + end + end + + defp merge_code_segment(node, []), do: [node] + + defp code_segment({:code, attrs, inner, meta}), do: {attrs, inner, meta} + + defp code_segment({:a, attrs, [{:code, code_attrs, inner, code_meta}], meta}) do + {code_attrs, [{:a, attrs, inner, meta}], code_meta} + end + + defp code_segment(_), do: nil + + defp code_joiner(inner) do + if String.ends_with?(text(inner), "="), do: [" "], else: [] + end + + defp merge_code_attrs(left, right) do + Enum.reduce_while(right, {:ok, left}, fn {key, value}, {:ok, attrs} -> + case Keyword.fetch(attrs, key) do + :error -> {:cont, {:ok, attrs ++ [{key, value}]}} + {:ok, ^value} -> {:cont, {:ok, attrs}} + {:ok, _value} -> {:halt, :error} + end + end) + end + @doc """ Returns text content from the given AST. """ diff --git a/lib/ex_doc/language/elixir.ex b/lib/ex_doc/language/elixir.ex index 0c8db5f3c..48edc6472 100644 --- a/lib/ex_doc/language/elixir.ex +++ b/lib/ex_doc/language/elixir.ex @@ -3,7 +3,7 @@ defmodule ExDoc.Language.Elixir do @behaviour ExDoc.Language - alias ExDoc.Autolink + alias ExDoc.{Autolink, DocAST} alias ExDoc.Language.Source @impl true @@ -372,7 +372,10 @@ defmodule ExDoc.Language.Elixir do true = config.language == __MODULE__ config = %{config | force_module_prefix: false} - walk_doc(ast, config) + + ast + |> walk_doc(config) + |> DocAST.merge_code_segments() end @impl true diff --git a/lib/ex_doc/language/erlang.ex b/lib/ex_doc/language/erlang.ex index 2fa871e27..45c2910c7 100644 --- a/lib/ex_doc/language/erlang.ex +++ b/lib/ex_doc/language/erlang.ex @@ -4,7 +4,7 @@ defmodule ExDoc.Language.Erlang do @behaviour ExDoc.Language alias ExDoc.Language.Source - alias ExDoc.{Autolink, Refs} + alias ExDoc.{Autolink, DocAST, Refs} @impl true @spec module_data(atom, any, any) :: @@ -199,7 +199,10 @@ defmodule ExDoc.Language.Erlang do true = config.language == __MODULE__ config = %{config | force_module_prefix: true} - walk_doc(ast, config) + + ast + |> walk_doc(config) + |> DocAST.merge_code_segments() end @impl true diff --git a/test/ex_doc/doc_ast_test.exs b/test/ex_doc/doc_ast_test.exs index c82eab4f4..792aa96bb 100644 --- a/test/ex_doc/doc_ast_test.exs +++ b/test/ex_doc/doc_ast_test.exs @@ -160,6 +160,63 @@ defmodule ExDoc.DocASTTest do end end + describe "merge_code_segments/1" do + test "merges adjacent code and linked-code nodes" do + ast = [ + {:code, [class: "inline"], ["{"], %{line: 1}}, + " ", + {:a, [href: "#type"], [{:code, [class: "inline"], ["type()"], %{}}], %{}}, + " ", + {:code, [class: "inline"], ["}"], %{}} + ] + + assert DocAST.merge_code_segments(ast) == + [ + {:code, [class: "inline"], + ["{", " ", {:a, [href: "#type"], ["type()"], %{}}, " ", "}"], %{line: 1}} + ] + end + + test "merges code nodes separated by whitespace and keeps code blocks unchanged" do + code = {:code, [], ["foo"], %{}} + + assert DocAST.merge_code_segments([code, " ", code]) == + [{:code, [], ["foo", " ", "foo"], %{}}] + + assert DocAST.merge_code_segments([code, "\n", code]) == [code, "\n", code] + + assert DocAST.merge_code_segments([code, " and ", code]) == [code, " and ", code] + + assert DocAST.merge_code_segments({:pre, [], [code, code], %{}}) == + {:pre, [], [code, code], %{}} + end + + test "preserves attributes and stops at conflicts" do + left = {:code, [class: "inline"], ["foo"], %{}} + right = {:code, [class: "inline", id: "bar"], ["bar"], %{}} + conflict = {:code, [class: "other"], ["baz"], %{}} + + assert DocAST.merge_code_segments([left, right, conflict]) == + [ + {:code, [class: "inline", id: "bar"], ["foo", "bar"], %{}}, + conflict + ] + end + + test "preserves spacing after an assignment operator" do + ast = [ + {:code, [class: "inline"], ["level ="], %{}}, + {:a, [href: "#level"], [{:code, [class: "inline"], ["logger:level/0"], %{}}], %{}} + ] + + assert DocAST.merge_code_segments(ast) == + [ + {:code, [class: "inline"], + ["level =", " ", {:a, [href: "#level"], ["logger:level/0"], %{}}], %{}} + ] + end + end + describe "headers" do test "adds and extracts anchored headers" do assert """ diff --git a/test/ex_doc/formatter/erlang_test.exs b/test/ex_doc/formatter/erlang_test.exs index b0941b28a..d950ee53f 100644 --- a/test/ex_doc/formatter/erlang_test.exs +++ b/test/ex_doc/formatter/erlang_test.exs @@ -1,5 +1,5 @@ defmodule ExDoc.Formatter.ErlangTest do - use ExUnit.Case, async: true + use ExUnit.Case, async: false import TestHelper @moduletag :tmp_dir diff --git a/test/ex_doc/formatter/html/search_data_test.exs b/test/ex_doc/formatter/html/search_data_test.exs index 343e8c71e..657b184c3 100644 --- a/test/ex_doc/formatter/html/search_data_test.exs +++ b/test/ex_doc/formatter/html/search_data_test.exs @@ -1,5 +1,5 @@ defmodule ExDoc.Formatter.HTML.SearchDataTest do - use ExUnit.Case, async: true + use ExUnit.Case, async: false import TestHelper @moduletag :tmp_dir diff --git a/test/ex_doc/language/elixir_test.exs b/test/ex_doc/language/elixir_test.exs index cb0d862cc..b222412d6 100644 --- a/test/ex_doc/language/elixir_test.exs +++ b/test/ex_doc/language/elixir_test.exs @@ -4,6 +4,11 @@ defmodule ExDoc.Language.ElixirTest do doctest ExDoc.Autolink describe "autolink_doc/2" do + test "adjacent code and module links" do + assert autolink_doc("`%{` `String` `}`") == + ~s|%{ String }| + end + test "elixir stdlib module" do assert autolink_doc("`String`") == ~s|String| diff --git a/test/ex_doc/language/erlang_test.exs b/test/ex_doc/language/erlang_test.exs index 702793fe6..6dad99cd5 100644 --- a/test/ex_doc/language/erlang_test.exs +++ b/test/ex_doc/language/erlang_test.exs @@ -150,6 +150,18 @@ defmodule ExDoc.Language.ErlangTest do ~s|array:array()| end + test "adjacent code and type links" do + ast = [ + {:code, [], ["{"], %{}}, + {:a, [href: "#integer()", rel: "https://erlang.org/doc/link/seetype"], + [{:code, [], ["integer()"], %{}}], %{}}, + {:code, [], ["}"], %{}} + ] + + assert autolink(ast) == + ~s|{integer()}| + end + @myList (if :erlang.system_info(:otp_release) >= ~c"27" do "t:myList/0" else diff --git a/test/ex_doc/retriever/erlang_test.exs b/test/ex_doc/retriever/erlang_test.exs index 52d91a010..c2ddb6d7f 100644 --- a/test/ex_doc/retriever/erlang_test.exs +++ b/test/ex_doc/retriever/erlang_test.exs @@ -1,5 +1,5 @@ defmodule ExDoc.Retriever.ErlangTest do - use ExUnit.Case, async: true + use ExUnit.Case, async: false alias ExDoc.{Retriever, DocAST, Language.Erlang, DocGroupNode} import TestHelper diff --git a/test/test_helper.exs b/test/test_helper.exs index b2c05b4de..031a581a1 100644 --- a/test/test_helper.exs +++ b/test/test_helper.exs @@ -48,6 +48,7 @@ defmodule TestHelper do end def erlc(context, module, code, opts \\ []) do + false = Map.get(context, :async, false) dir = context.tmp_dir docs = Keyword.get(opts, :docs, true) @@ -73,6 +74,7 @@ defmodule TestHelper do true = Code.prepend_path(ebin_dir) {:module, ^module} = :code.load_file(module) + ExDoc.Refs.clear() ExUnit.Callbacks.on_exit(fn -> :code.purge(module)