From fb0b18c2f18b29c4a417f0ac99fdcba4fc693f46 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lukas=20Backstr=C3=B6m?= Date: Thu, 29 Oct 2026 14:32:11 +0100 Subject: [PATCH 1/4] doc_ast: Merge adjacent code segments Autolinking can split one code expression into linked and unlinked code nodes. HTML then renders visible gaps between segments. Normalize adjacent code nodes after autolinking for both Erlang and Elixir while preserving link boundaries. Assisted-by: Codex:gpt-5.6-sol --- lib/ex_doc/doc_ast.ex | 64 ++++++++++++++++++++++++++++ lib/ex_doc/language/elixir.ex | 7 ++- lib/ex_doc/language/erlang.ex | 7 ++- test/ex_doc/doc_ast_test.exs | 57 +++++++++++++++++++++++++ test/ex_doc/language/elixir_test.exs | 5 +++ test/ex_doc/language/erlang_test.exs | 12 ++++++ 6 files changed, 148 insertions(+), 4 deletions(-) diff --git a/lib/ex_doc/doc_ast.ex b/lib/ex_doc/doc_ast.ex index 7f7cbbcdf..9cffa1934 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(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/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 From 30806840f7a47b9a891357d3f7c15a687277c4d7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lukas=20Backstr=C3=B6m?= Date: Thu, 29 Oct 2026 14:32:25 +0100 Subject: [PATCH 2/4] tests: Serialize Erlang fixture compilation `erlc/4` reloads fixture modules and clears the global documentation reference cache. Async callers can expose stale reference data while other suites autolink documentation. Require synchronous callers and clear cached references immediately after loading each fixture. Assisted-by: Codex:gpt-5.6-sol --- test/ex_doc/formatter/erlang_test.exs | 2 +- test/ex_doc/formatter/html/search_data_test.exs | 2 +- test/ex_doc/retriever/erlang_test.exs | 2 +- test/test_helper.exs | 2 ++ 4 files changed, 5 insertions(+), 3 deletions(-) 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/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) From 1c87fd4b7f76dd6d3468953f15d044ac32ee2189 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lukas=20Backstr=C3=B6m?= Date: Thu, 29 Oct 2026 14:32:34 +0100 Subject: [PATCH 3/4] ci: Pin old OTP jobs to Ubuntu 24.04 Ubuntu 26.04 does not support setup-beam artifacts for OTP 25. Its OTP 26.2.5.21 artifact also contains fallback documentation chunks that mark documented OTP modules and functions as hidden. Run OTP 25 and OTP 26 jobs on Ubuntu 24.04, whose artifacts contain usable documentation chunks. Keep newer jobs on current runners. Assisted-by: Codex:gpt-5.6-sol --- .github/workflows/ci.yml | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) 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 From 07a3cc819c0206c5dd3b7c9d51d95f1a9e1c8ca5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Valim?= Date: Thu, 29 Oct 2026 18:45:13 +0100 Subject: [PATCH 4/4] Update lib/ex_doc/doc_ast.ex --- lib/ex_doc/doc_ast.ex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/ex_doc/doc_ast.ex b/lib/ex_doc/doc_ast.ex index 9cffa1934..9439e8b1b 100644 --- a/lib/ex_doc/doc_ast.ex +++ b/lib/ex_doc/doc_ast.ex @@ -205,7 +205,7 @@ defmodule ExDoc.DocAST do def merge_code_segments(ast), do: ast defp merge_code_segment(right, [separator, left | rest]) when is_binary(separator) do - with "" <- String.trim(separator), + 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),