From 38304be5592732150ba897e6b43d2e9a59c5b297 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Valim?= 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 7dce76200209..05acd5cf5f96 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. From 6e9c07f357b9cc21f65473313b7725ac5a936a94 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Valim?= Date: Fri, 18 Oct 2024 18:06:22 +0200 Subject: [PATCH 2/2] Update eep48_chapter.md --- lib/kernel/doc/guides/eep48_chapter.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/lib/kernel/doc/guides/eep48_chapter.md b/lib/kernel/doc/guides/eep48_chapter.md index 05acd5cf5f96..2f0704e666c2 100644 --- a/lib/kernel/doc/guides/eep48_chapter.md +++ b/lib/kernel/doc/guides/eep48_chapter.md @@ -148,11 +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">>`. -- **`source := binary()`** - the location of the source file for this module. - Applies only to the module metadata. +- **`source_path := binary()`** - the absolute 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). +- **`source_annos := [erl_anno:anno()]`** - a list of source code locations. + You may either store one for each clause or only for the first clause. Any key may be added to Metadata at any time. Keys that are frequently used by the community can be standardized in future versions.