Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -65,25 +65,30 @@ jobs:
file_pattern: formatters

elixir:
runs-on: ubuntu-latest
runs-on: ${{ matrix.os }}
strategy:
fail-fast: false
matrix:
include:
# 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
Expand Down
64 changes: 64 additions & 0 deletions lib/ex_doc/doc_ast.ex
Original file line number Diff line number Diff line change
Expand Up @@ -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.
"""
Expand Down
7 changes: 5 additions & 2 deletions lib/ex_doc/language/elixir.ex
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
7 changes: 5 additions & 2 deletions lib/ex_doc/language/erlang.ex
Original file line number Diff line number Diff line change
Expand Up @@ -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) ::
Expand Down Expand Up @@ -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
Expand Down
57 changes: 57 additions & 0 deletions test/ex_doc/doc_ast_test.exs
Original file line number Diff line number Diff line change
Expand Up @@ -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 """
Expand Down
2 changes: 1 addition & 1 deletion test/ex_doc/formatter/erlang_test.exs
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
defmodule ExDoc.Formatter.ErlangTest do
use ExUnit.Case, async: true
use ExUnit.Case, async: false
import TestHelper

@moduletag :tmp_dir
Expand Down
2 changes: 1 addition & 1 deletion test/ex_doc/formatter/html/search_data_test.exs
Original file line number Diff line number Diff line change
@@ -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
Expand Down
5 changes: 5 additions & 0 deletions test/ex_doc/language/elixir_test.exs
Original file line number Diff line number Diff line change
Expand Up @@ -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|<code class="inline">%{ <a href="https://elixir.hexdocs.pm/String.html">String</a> }</code>|
end

test "elixir stdlib module" do
assert autolink_doc("`String`") ==
~s|<a href="https://elixir.hexdocs.pm/String.html"><code class="inline">String</code></a>|
Expand Down
12 changes: 12 additions & 0 deletions test/ex_doc/language/erlang_test.exs
Original file line number Diff line number Diff line change
Expand Up @@ -150,6 +150,18 @@ defmodule ExDoc.Language.ErlangTest do
~s|<a href="https://www.erlang.org/doc/apps/stdlib/array.html#t:array/0"><code>array:array()</code></a>|
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|<code>{<a href="https://www.erlang.org/doc/apps/erts/erlang.html#t:integer/0">integer()</a>}</code>|
end

@myList (if :erlang.system_info(:otp_release) >= ~c"27" do
"t:myList/0"
else
Expand Down
2 changes: 1 addition & 1 deletion test/ex_doc/retriever/erlang_test.exs
Original file line number Diff line number Diff line change
@@ -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

Expand Down
2 changes: 2 additions & 0 deletions test/test_helper.exs
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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)
Expand Down
Loading