Autolink references in deprecation messages

[rhcarvalho]

I was reading about the upcoming deprecation of String.to_atom/1 in Elixir 1.21, and noticed that references in the documentation did not link to the recommended alternative.

At first I thought it might have been an oversight in the Elixir documentation, but then realized that it is actually a deliberate limitation of ExDoc.

After doing some research, I found that the documentation storage and format is described by EEP 48. The Metadata.deprecated field is intentionally a plain text string, not Markdown.

Prior discussions on the topic:

• OP tried to use Markdown, José explained why not and suggested links can be part of the docstring instead:

  • Add support for links in the @deprecated tags #1159
  • Text in @deprecated is not processed using Markdown #1566

  In the case of String.to_atom/1, it has been effectively renamed to String.to_unsafe_atom/1 and the documentation moved there. Duplicating the documentation just to repeat the deprecation notice and add a link doesn't really improve the UX.

• Refused proposal for an additional autolink syntax (in docstrings):

  • Proposal: Autolink with [code] #1663
  • José wrote:

    [...] The whole point of foo/2 was precisely so simply referring to the code was enough to make it become a link because that is going to be more useful to the reader.

With the constraint of not introducing new syntax, not expecting any changes to how documentation and deprecation messages are written, and avoiding ambiguous cases that could lead to false positives, I found that we can improve the experience for the common case of referring to another function via MFA or FA pattern (which is the dominant pattern in the elixir-lang/elixir repo).

Before

https://elixir.hexdocs.pm/main/String.html#to_atom/1

After

[github-actions]

📦 Docs artifacts are ready: https://github.com/elixir-lang/ex_doc/actions/runs/38260781787/artifacts/11752318389

[rhcarvalho]

Rebased to fix conflict after removal of pre-existing dead code via #2275, no changes.

[rhcarvalho]

(Aware and working on the test failure, an order-dependent flaky test caused by ExDoc.Refs.insert with stdlib modules like String)

[rhcarvalho]

The test failure on Elixir 1.15 was related to a mistake I made in the new tests. It could have failed in any Elixir version, as it was related to scheduling order and who populated an ETS table first.

Pushed a new commit with a fix. All test-related modules start with AutolinkTest and each test use independent module names, preventing collision.

Note this was a change only to tests we are adding in this PR. No changes to existing tests in main.