From fe8a5156b467028a4b83787a04d7acae1b0c4358 Mon Sep 17 00:00:00 2001 From: "Paulo F. Oliveira" Date: Sun, 10 Sep 2023 12:26:07 +0100 Subject: [PATCH 01/15] Move deprecated to its semantic equivalent This is context-dependant, so I used code everywhere which is what seem to make th most sense --- lib/edoc/doc/overview.edoc | 6 +++--- lib/edoc/test/edoc_SUITE_data/overview.edoc | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/lib/edoc/doc/overview.edoc b/lib/edoc/doc/overview.edoc index 487033b87182..de1859fd2953 100644 --- a/lib/edoc/doc/overview.edoc +++ b/lib/edoc/doc/overview.edoc @@ -546,7 +546,7 @@ documentation. === Empty lines separate paragraphs === Leaving an empty line in XHTML text (i.e., a line which except for -any leading start-of-comment '%' characters contains only +any leading start-of-comment '%' characters contains only whitespace), will make EDoc split the text before and after the empty line into separate paragraphs. For example: ```%% @doc This will all be part of the first paragraph. @@ -703,7 +703,7 @@ information. User-defined macros override predefined macros.
@{@date}
-
Expands to the current date, as "Month Day Year", +
Expands to the current date, as "Month Day Year", e.g. "{@date}".
@{@link reference. @@ -726,7 +726,7 @@ information. User-defined macros override predefined macros. see {@section Headings} for more information.
@{@time}
-
Expands to the current time, as "Hr:Min:Sec", +
Expands to the current time, as "Hr:Min:Sec", e.g. "{@time}".
@{@type diff --git a/lib/edoc/test/edoc_SUITE_data/overview.edoc b/lib/edoc/test/edoc_SUITE_data/overview.edoc index 0da5a2175969..7236acff0f0e 100644 --- a/lib/edoc/test/edoc_SUITE_data/overview.edoc +++ b/lib/edoc/test/edoc_SUITE_data/overview.edoc @@ -432,7 +432,7 @@ documentation. === Empty lines separate paragraphs === Leaving an empty line in XHTML text (i.e., a line which except for -any leading start-of-comment '%' characters contains only +any leading start-of-comment '%' characters contains only whitespace), will make EDoc split the text before and after the empty line into separate paragraphs. For example: ```%% @doc This will all be part of the first paragraph. @@ -583,7 +583,7 @@ information.
@{@date}
-
Expands to the current date, as "Month Day Year", +
Expands to the current date, as "Month Day Year", e.g. "{@date}".
@{@docRoot}
@@ -628,7 +628,7 @@ information. {@section Escape sequences} below.)
@{@time}
-
Expands to the current time, as "Hr:Min:Sec", +
Expands to the current time, as "Hr:Min:Sec", e.g. "{@time}".
From 458616e51c942ccfe2cafd2d9e986217e6125577 Mon Sep 17 00:00:00 2001 From: "Paulo F. Oliveira" Date: Sun, 10 Sep 2023 13:11:06 +0100 Subject: [PATCH 02/15] Prepare for upcoming changes --- lib/edoc/doc/overview.edoc | 2 +- lib/edoc/test/edoc_SUITE_data/overview.edoc | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/edoc/doc/overview.edoc b/lib/edoc/doc/overview.edoc index de1859fd2953..5eba4788d95d 100644 --- a/lib/edoc/doc/overview.edoc +++ b/lib/edoc/doc/overview.edoc @@ -598,7 +598,7 @@ The above expansions take place before XML parsing. Writing a URL within brackets, as in "`[http://www.w3c.org/]'", will generate a hyperlink such as [http://www.w3c.org/], using the URL both for the destination and the label of the reference, equivalent to writing -"`http://www.w3c.org/'". This +"`http://www.w3c.org/'". This short-hand keeps external URL references short and readable. The recognized protocols are `http', `ftp', and `file'. This expansion takes place before XML parsing. diff --git a/lib/edoc/test/edoc_SUITE_data/overview.edoc b/lib/edoc/test/edoc_SUITE_data/overview.edoc index 7236acff0f0e..32c8219ca8d3 100644 --- a/lib/edoc/test/edoc_SUITE_data/overview.edoc +++ b/lib/edoc/test/edoc_SUITE_data/overview.edoc @@ -484,7 +484,7 @@ The above expansions take place before XML parsing. Writing a URL within brackets, as in "`[http://www.w3c.org/]'", will generate a hyperlink such as [http://www.w3c.org/], using the URL both for the destination and the label of the reference, equivalent to writing -"`http://www.w3c.org/'". This +"`http://www.w3c.org/'". This short-hand keeps external URL references short and readable. The recognized protocols are `http', `ftp', and `file'. This expansion takes place before XML parsing. From 1501b271f8e9d829f44801b51cd5a40bff6f7ee9 Mon Sep 17 00:00:00 2001 From: "Paulo F. Oliveira" Date: Sun, 10 Sep 2023 13:15:36 +0100 Subject: [PATCH 03/15] Handle external links e.g. [https://erlang.org] edoc is, funny enough, code backwards :-) --- lib/edoc/src/edoc_wiki.erl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/edoc/src/edoc_wiki.erl b/lib/edoc/src/edoc_wiki.erl index 903d69e84cf1..15cef50b78cc 100644 --- a/lib/edoc/src/edoc_wiki.erl +++ b/lib/edoc/src/edoc_wiki.erl @@ -273,7 +273,7 @@ expand_uri(Cs, L, As) -> expand(Cs, L, [$[ | As]). expand_uri([$] | Cs], L, Us, As) -> - expand(Cs, L, push_uri(Us, ">tt/<" ++ Us ++ ">tt<", As)); + expand(Cs, L, push_uri(Us, ">edoc/<" ++ Us ++ ">edoc<", As)); expand_uri([$\s = C | Cs], L, Us, As) -> expand_uri(Cs, 0, L, [C], Us, As); expand_uri([$\t = C | Cs], L, Us, As) -> From 05ccb67a2bb0a6a06ff70c44c0eb2b29b8933137 Mon Sep 17 00:00:00 2001 From: "Paulo F. Oliveira" Date: Sun, 10 Sep 2023 13:19:51 +0100 Subject: [PATCH 04/15] Handle functions without typespec e.g. fn() -> 'end'. --- lib/edoc/src/edoc_layout.erl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/edoc/src/edoc_layout.erl b/lib/edoc/src/edoc_layout.erl index fb5e9edf2e46..e3984dee68eb 100644 --- a/lib/edoc/src/edoc_layout.erl +++ b/lib/edoc/src/edoc_layout.erl @@ -426,7 +426,7 @@ label_anchor(Content, E) -> %% This is currently only done for functions without type spec. signature(Es, Name) -> - [{tt, [Name, "("] ++ seq(fun arg/1, Es) ++ [") -> any()"]}]. + [{code, [Name, "("] ++ seq(fun arg/1, Es) ++ [") -> any()"]}]. arg(#xmlElement{content = Es}) -> [get_text(argName, Es)]. From 7226656f289eaab0e652b678224dcc9e85a7c63b Mon Sep 17 00:00:00 2001 From: "Paulo F. Oliveira" Date: Sun, 10 Sep 2023 13:32:38 +0100 Subject: [PATCH 05/15] Handle parameters e.g. %% @param Var The variable --- lib/edoc/src/edoc_layout.erl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/edoc/src/edoc_layout.erl b/lib/edoc/src/edoc_layout.erl index e3984dee68eb..4d8175cb262f 100644 --- a/lib/edoc/src/edoc_layout.erl +++ b/lib/edoc/src/edoc_layout.erl @@ -441,7 +441,7 @@ params(Es) -> if As1 == [] -> []; true -> - [ { [{tt, [A]}, ": "] ++ D ++ [br, ?NL] } + [ { [{code, [A]}, ": "] ++ D ++ [br, ?NL] } || {A, D} <- As1] end. From d14b8381c0701e46ce2b57b080a15148e8d97396 Mon Sep 17 00:00:00 2001 From: "Paulo F. Oliveira" Date: Sun, 10 Sep 2023 13:35:15 +0100 Subject: [PATCH 06/15] Handle thrown % @throws 'Something' --- lib/edoc/src/edoc_layout.erl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/edoc/src/edoc_layout.erl b/lib/edoc/src/edoc_layout.erl index 4d8175cb262f..7450a3abe6cf 100644 --- a/lib/edoc/src/edoc_layout.erl +++ b/lib/edoc/src/edoc_layout.erl @@ -460,7 +460,7 @@ throws(Es, Opts) -> [] -> []; Es1 -> %% Doesn't use format_type; keep it short! - [{p, (["throws ", {tt, t_utype(get_elem(type, Es1), Opts)}] + [{p, (["throws ", {code, t_utype(get_elem(type, Es1), Opts)}] ++ local_defs(get_elem(localdef, Es1), Opts))}, ?NL] end. From fdfc451d832824ab714795d5bc755d4c9cc14670 Mon Sep 17 00:00:00 2001 From: "Paulo F. Oliveira" Date: Sun, 10 Sep 2023 13:40:23 +0100 Subject: [PATCH 07/15] Handle abstract data types e.g. %% @type myList(X). A special kind of lists ... --- lib/edoc/src/edoc_layout.erl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/edoc/src/edoc_layout.erl b/lib/edoc/src/edoc_layout.erl index 7450a3abe6cf..3c2bb2a90a40 100644 --- a/lib/edoc/src/edoc_layout.erl +++ b/lib/edoc/src/edoc_layout.erl @@ -497,7 +497,7 @@ typedef(Es, Opts) -> Name = ([t_name(get_elem(erlangName, Es), Opts), "("] ++ seq(t_utype_elem_fun(Opts), get_content(argtypes, Es), [")"])), (case get_elem(type, Es) of - [] -> [{b, ["abstract datatype"]}, ": ", {tt, Name}]; + [] -> [{b, ["abstract datatype"]}, ": ", {code, Name}]; Type -> format_type(Name, Name, Type, [], Opts) end ++ local_defs(get_elem(localdef, Es), Opts)). From 180733fbe32b334c5f725481c32cfd8030be48d3 Mon Sep 17 00:00:00 2001 From: "Paulo F. Oliveira" Date: Sun, 10 Sep 2023 13:44:55 +0100 Subject: [PATCH 08/15] Handle limited formatting When no EDoc is actually present e.g. id(Var) -> Var. --- lib/edoc/src/edoc_layout.erl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/edoc/src/edoc_layout.erl b/lib/edoc/src/edoc_layout.erl index 3c2bb2a90a40..47fb78e1882f 100644 --- a/lib/edoc/src/edoc_layout.erl +++ b/lib/edoc/src/edoc_layout.erl @@ -540,7 +540,7 @@ format_spec(Name, Type, Defs, #opts{pretty_printer = erl_pp}=Opts) -> format_spec(Sep, Type, Defs, Opts) -> %% Very limited formatting. Br = if Defs =:= [] -> br; true -> [] end, - [{tt, t_clause(Sep, Type, Opts)}, Br]. + [{code, t_clause(Sep, Type, Opts)}, Br]. t_clause(Name, Type, Opts) -> #xmlElement{content = [#xmlElement{name = 'fun', content = C}]} = Type, From cc4d7f084b8aa7879b62514f7965e60cf7b032e7 Mon Sep 17 00:00:00 2001 From: "Paulo F. Oliveira" Date: Sun, 10 Sep 2023 13:46:11 +0100 Subject: [PATCH 09/15] Handle types e.g. % @type str() = string(). --- lib/edoc/src/edoc_layout.erl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/edoc/src/edoc_layout.erl b/lib/edoc/src/edoc_layout.erl index 47fb78e1882f..39daf67f75f5 100644 --- a/lib/edoc/src/edoc_layout.erl +++ b/lib/edoc/src/edoc_layout.erl @@ -567,7 +567,7 @@ format_type(Prefix, Name, Type, Last, #opts{pretty_printer = erl_pp}=Opts) -> format_type(Prefix, Name, Type, Last, Opts#opts{pretty_printer =''}) end; format_type(Prefix, _Name, Type, Last, Opts) -> - [{tt, Prefix ++ [" = "] ++ t_utype(Type, Opts) ++ Last}]. + [{code, Prefix ++ [" = "] ++ t_utype(Type, Opts) ++ Last}]. pp_type(Prefix, Type, Opts) -> Atom = list_to_atom(lists:duplicate(string:length(Prefix), $a)), From 904ecf19b186c13d89ef260b119d9ee84470b269 Mon Sep 17 00:00:00 2001 From: "Paulo F. Oliveira" Date: Sun, 10 Sep 2023 13:48:38 +0100 Subject: [PATCH 10/15] Handle equivalence e.g. % @equiv sth(Var, []) --- lib/edoc/src/edoc_layout.erl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/edoc/src/edoc_layout.erl b/lib/edoc/src/edoc_layout.erl index 39daf67f75f5..6d2a665d403d 100644 --- a/lib/edoc/src/edoc_layout.erl +++ b/lib/edoc/src/edoc_layout.erl @@ -672,7 +672,7 @@ equiv(Es, P) -> case get_content(expr, Es1) of [] -> []; [Expr] -> - Expr1 = [{tt, [Expr]}], + Expr1 = [{code, [Expr]}], Expr2 = case get_elem(see, Es1) of [] -> Expr1; From 96d7199fbd870162382c46cef9f0ef04cb8b1c9d Mon Sep 17 00:00:00 2001 From: "Paulo F. Oliveira" Date: Sun, 10 Sep 2023 13:51:30 +0100 Subject: [PATCH 11/15] Handle behavior names (just define a behavior module to see how it works in terms of output) --- lib/edoc/src/edoc_layout.erl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/edoc/src/edoc_layout.erl b/lib/edoc/src/edoc_layout.erl index 6d2a665d403d..c03f369eda1e 100644 --- a/lib/edoc/src/edoc_layout.erl +++ b/lib/edoc/src/edoc_layout.erl @@ -745,7 +745,7 @@ behaviours(Es, Name, Opts) -> [br, " Optional callback functions: "] ++ seq(CBFun, OCBs, ["."]) end, - [{p, ([{b, ["This module defines the ", {tt, [Name]}, + [{p, ([{b, ["This module defines the ", {code, [Name]}, " behaviour."]}] ++ Req ++ Opt)}, ?NL] From fabbc713ed051d9ddce24517c7240716379298b5 Mon Sep 17 00:00:00 2001 From: "Paulo F. Oliveira" Date: Sun, 10 Sep 2023 13:54:07 +0100 Subject: [PATCH 12/15] Handle name of behaviour implementations e.g. -behaviour(gen_server). --- lib/edoc/src/edoc_layout.erl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/edoc/src/edoc_layout.erl b/lib/edoc/src/edoc_layout.erl index c03f369eda1e..0df596de46c6 100644 --- a/lib/edoc/src/edoc_layout.erl +++ b/lib/edoc/src/edoc_layout.erl @@ -752,7 +752,7 @@ behaviours(Es, Name, Opts) -> end). behaviour(E=#xmlElement{content = Es}) -> - see(E, [{tt, Es}]). + see(E, [{code, Es}]). callback(E=#xmlElement{}, Opts) -> Name = get_attrval(name, E), From dfc710404d3dd3a34a43b6a18dbe245d743294ee Mon Sep 17 00:00:00 2001 From: "Paulo F. Oliveira" Date: Sun, 10 Sep 2023 13:55:58 +0100 Subject: [PATCH 13/15] Handle required callbacks --- lib/edoc/src/edoc_layout.erl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/edoc/src/edoc_layout.erl b/lib/edoc/src/edoc_layout.erl index 0df596de46c6..451d467c4787 100644 --- a/lib/edoc/src/edoc_layout.erl +++ b/lib/edoc/src/edoc_layout.erl @@ -757,7 +757,7 @@ behaviour(E=#xmlElement{content = Es}) -> callback(E=#xmlElement{}, Opts) -> Name = get_attrval(name, E), Arity = get_attrval(arity, E), - [{tt, [atom(Name, Opts), "/", Arity]}]. + [{code, [atom(Name, Opts), "/", Arity]}]. authors(Es) -> case get_elem(author, Es) of From a1bac198c0b1a8fb27c4760194066535f0ece6d4 Mon Sep 17 00:00:00 2001 From: "Paulo F. Oliveira" Date: Sun, 10 Sep 2023 13:58:44 +0100 Subject: [PATCH 14/15] Handle mailto --- lib/edoc/src/edoc_layout.erl | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/edoc/src/edoc_layout.erl b/lib/edoc/src/edoc_layout.erl index 451d467c4787..09788df2edc8 100644 --- a/lib/edoc/src/edoc_layout.erl +++ b/lib/edoc/src/edoc_layout.erl @@ -782,11 +782,11 @@ author(E=#xmlElement{}) -> Mail = get_attrval(email, E), URI = get_attrval(website, E), (if Name == Mail -> - [{a, [{href, "mailto:" ++ Mail}],[{tt, [Mail]}]}]; + [{a, [{href, "mailto:" ++ Mail}],[{code, [Mail]}]}]; true -> if Mail == "" -> [Name]; true -> [Name, " (", {a, [{href, "mailto:" ++ Mail}], - [{tt, [Mail]}]}, ")"] + [{code, [Mail]}]}, ")"] end end ++ if URI == "" -> From 901a320ba06fb16951dd7c366791b7459f018c77 Mon Sep 17 00:00:00 2001 From: "Paulo F. Oliveira" Date: Sun, 10 Sep 2023 14:00:19 +0100 Subject: [PATCH 15/15] Handle author website e.g. %% @author carlsson.richard@gmail.com [http://example.net/richardc/] --- lib/edoc/src/edoc_layout.erl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/edoc/src/edoc_layout.erl b/lib/edoc/src/edoc_layout.erl index 09788df2edc8..802e88b12440 100644 --- a/lib/edoc/src/edoc_layout.erl +++ b/lib/edoc/src/edoc_layout.erl @@ -793,7 +793,7 @@ author(E=#xmlElement{}) -> []; true -> [" [", {em, ["web site:"]}, " ", - {tt, [{a, [{href, URI}, {target, "_top"}], [URI]}]}, + {code, [{a, [{href, URI}, {target, "_top"}], [URI]}]}, "]"] end).