File 0133-Update-attributes-in-EEP-48.patch of Package erlang
From 38304be5592732150ba897e6b43d2e9a59c5b297 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jos=C3=A9=20Valim?= <jose.valim@dashbit.co>
Date: Wed, 16 Oct 2024 10:17:23 +0200
Subject: [PATCH 1/2] Update attributes in EEP 48
Currently, editors and documentation tooling must
parse metadata from several chunks in order to
function properly. The source is in the compilation
chunk. The behaviours a module implements is in the
attributes chunk. And the annotation of any definition
requires traversing abstract code.
With this commit, we introduce three new attributes,
`:behaviours`, `:source`, and `:source_anno`, so
this additional data can be standardized and easily
located.
We also remove `edit_url` from the standard. As it is
not used by any of the official tooling, languages, or
libraries.
---
lib/kernel/doc/guides/eep48_chapter.md | 14 ++++++++++----
1 file changed, 10 insertions(+), 4 deletions(-)
diff --git a/lib/kernel/doc/guides/eep48_chapter.md b/lib/kernel/doc/guides/eep48_chapter.md
index 7dce762002..05acd5cf5f 100644
--- a/lib/kernel/doc/guides/eep48_chapter.md
+++ b/lib/kernel/doc/guides/eep48_chapter.md
@@ -105,8 +105,8 @@ For each entry in Docs, we have:
`callback`. Other languages will add their own. For instance, Elixir and LFE
might add `macro`.
-- **`Anno`** - annotation (line, column, file) of the module documentation or of
- the definition itself (see `m:erl_anno`).
+- **`Anno`** - annotation (line, column, file) of the module documentation
+ (see `m:erl_anno`).
- **`Signature`** - the signature of the entity. It is is a list of binaries.
Each entry represents a binary in the signature that can be joined with
@@ -134,6 +134,9 @@ information to each entry. This EEP documents the following metadata keys:
- **`authors := [binary()]`** - a list of authors as binaries.
+- **`behaviours := [module()]`** - a list of the behaviours implemented by
+ this module.
+
- **`cross_references := [module() | {module(), {Kind, Name, Arity}}]`** - a
list of modules or module entries that can be used as cross references when
generating documentation.
@@ -145,8 +148,11 @@ information to each entry. This EEP documents the following metadata keys:
- **`since := binary()`** - a binary representing the version such entry was
added, such as `<<"1.3.0">>` or `<<"20.0">>`.
-- **`edit_url := binary()`** - a binary representing a URL to change the
- documentation itself.
+- **`source := binary()`** - the location of the source file for this module.
+ Applies only to the module metadata.
+
+- **`source_anno := erl_anno:anno()`** - annotation metadata of the source
+ code (opposite to the annotation of the documentation attribute).
Any key may be added to Metadata at any time. Keys that are frequently used by
the community can be standardized in future versions.
--
2.43.0
