Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

edoc generates several returns for functions having several specification clauses #7576

Open
pguyot opened this issue Aug 19, 2023 · 0 comments
Assignees
Labels
bug Issue is reported as a bug team:VM Assigned to OTP team VM

Comments

@pguyot
Copy link
Contributor

pguyot commented Aug 19, 2023

Describe the bug
When generating documentation about a function that has a spec with several clauses and a @returns tag, edoc duplicates the content of the returns tag.

To Reproduce

Create a file edoc_returns.erl

-module(edoc_returns).
-export([is_pid_and_not_list/1]).

%% @doc This returns true or false.
%% @end
%% @returns a boolean depending on the passed type.
-spec is_pid_and_not_list(Pid :: pid()) -> true;
                         (List :: list()) -> false.
is_pid_and_not_list(Pid) when is_pid(Pid) -> true;
is_pid_and_not_list(List) when is_list(List) -> false.

Generate documentation with:

edoc:files(["edoc_returns.erl"], []).

Check generated edoc_returns.html. It does contain:

<p>returns: a boolean depending on the passed type.</p>
<p>returns: a boolean depending on the passed type.</p>

Expected behavior
The returns paragraph should not be duplicated.

Affected versions
OTP22 ({edoc,"EDoc","0.11"}) is not affected. This was observed with:

  • OTP23 ({edoc,"EDoc","0.12"})
  • OTP24 ({edoc,"EDoc, the Erlang documentation engine","1.1"})
  • OTP25 ({edoc,"EDoc, the Erlang documentation engine","1.2"})
  • OTP26 ({edoc,"EDoc, the Erlang documentation engine","1.2"})
  • and master (d3aa6c0)
@pguyot pguyot added the bug Issue is reported as a bug label Aug 19, 2023
pguyot added a commit to pguyot/edown that referenced this issue Aug 19, 2023
This is a workaround for bug erlang/otp#7576

Signed-off-by: Paul Guyot <pguyot@kallisys.net>
pguyot added a commit to pguyot/AtomVM that referenced this issue Aug 19, 2023
Implement the following functions:
- `erlang:spawn_link/1`
- `erlang:spawn_link/3`
- `erlang:exit/2`
- `lists:usort/1`
- `lists:usort/2`

Fix options of `spawn_opt/2` by factorizing it with `spawn_opt/4`
Also rewrite `spawn/1` and `spawn/3` in Erlang and update tests accordingly
Implement info `links` for `erlang:process_info/2`
Also narrow type specification of `erlang:process_info/2`
Also add documentation for `erlang:exit/1`
Fix a bug where exit reason was incorrectly a tuple for exception of class exit
No longer dump crash logs when exit reason is normal
Also update `.gitignore`
Also isolate libs tests
Also remove useless second installation of Erlang/OTP in documentation workflow
Also bump OTP and Elixir versions in documentation workflow
Also update edown with a patch to fix crash when parsing updated doc for
`erlang:process_info/2`
See:
- uwiger/edown#23
- erlang/otp#7576

Signed-off-by: Paul Guyot <pguyot@kallisys.net>
pguyot added a commit to pguyot/AtomVM that referenced this issue Aug 19, 2023
Implement the following functions:
- `erlang:spawn_link/1`
- `erlang:spawn_link/3`
- `erlang:exit/2`
- `lists:usort/1`
- `lists:usort/2`

Fix options of `spawn_opt/2` by factorizing it with `spawn_opt/4`
Also rewrite `spawn/1` and `spawn/3` in Erlang and update tests accordingly
Implement info `links` for `erlang:process_info/2`
Also narrow type specification of `erlang:process_info/2`
Also add documentation for `erlang:exit/1`
Fix a bug where exit reason was incorrectly a tuple for exception of class exit
No longer dump crash logs when exit reason is normal
Also update `.gitignore`
Also isolate libs tests
Also remove useless second installation of Erlang/OTP in documentation workflow
Also bump OTP and Elixir versions in documentation workflow
Also update edown with a patch to fix crash when parsing updated doc for
`erlang:process_info/2`
See:
- uwiger/edown#23
- erlang/otp#7576

Signed-off-by: Paul Guyot <pguyot@kallisys.net>
pguyot added a commit to pguyot/AtomVM that referenced this issue Aug 19, 2023
Implement the following functions:
- `erlang:spawn_link/1`
- `erlang:spawn_link/3`
- `erlang:exit/2`
- `lists:usort/1`
- `lists:usort/2`

Fix options of `spawn_opt/2` by factorizing it with `spawn_opt/4`
Also rewrite `spawn/1` and `spawn/3` in Erlang and update tests accordingly
Implement info `links` for `erlang:process_info/2`
Also narrow type specification of `erlang:process_info/2`
Also add documentation for `erlang:exit/1`
Fix a bug where exit reason was incorrectly a tuple for exception of class exit
No longer dump crash logs when exit reason is normal
Also update `.gitignore`
Also isolate libs tests
Also remove useless second installation of Erlang/OTP in documentation workflow
Also bump OTP and Elixir versions in documentation workflow
Also update edown with a patch to fix crash when parsing updated doc for
`erlang:process_info/2`
See:
- uwiger/edown#23
- erlang/otp#7576

Signed-off-by: Paul Guyot <pguyot@kallisys.net>
@rickard-green rickard-green added the team:VM Assigned to OTP team VM label Aug 21, 2023
pguyot added a commit to pguyot/AtomVM that referenced this issue Aug 24, 2023
Implement the following functions:
- `erlang:spawn_link/1`
- `erlang:spawn_link/3`
- `erlang:exit/2`
- `lists:usort/1`
- `lists:usort/2`

Fix options of `spawn_opt/2` by factorizing it with `spawn_opt/4`
Also rewrite `spawn/1` and `spawn/3` in Erlang and update tests accordingly
Implement info `links` for `erlang:process_info/2`
Also narrow type specification of `erlang:process_info/2`
Also add documentation for `erlang:exit/1`
Fix a bug where exit reason was incorrectly a tuple for exception of class exit
No longer dump crash logs when exit reason is normal
Also update `.gitignore`
Also isolate libs tests
Also remove useless second installation of Erlang/OTP in documentation workflow
Also bump OTP and Elixir versions in documentation workflow
Also update edown with a patch to fix crash when parsing updated doc for
`erlang:process_info/2`
See:
- uwiger/edown#23
- erlang/otp#7576

Signed-off-by: Paul Guyot <pguyot@kallisys.net>
pguyot added a commit to pguyot/AtomVM that referenced this issue Aug 25, 2023
Implement the following functions:
- `erlang:spawn_link/1`
- `erlang:spawn_link/3`
- `erlang:exit/2`
- `lists:usort/1`
- `lists:usort/2`

Fix options of `spawn_opt/2` by factorizing it with `spawn_opt/4`
Also rewrite `spawn/1` and `spawn/3` in Erlang and update tests accordingly
Implement info `links` for `erlang:process_info/2`
Also narrow type specification of `erlang:process_info/2`
Also add documentation for `erlang:exit/1`
Fix a bug where exit reason was incorrectly a tuple for exception of class exit
No longer dump crash logs when exit reason is normal
Also update `.gitignore`
Also isolate libs tests
Also remove useless second installation of Erlang/OTP in documentation workflow
Also bump OTP and Elixir versions in documentation workflow
Also update edown with a patch to fix crash when parsing updated doc for
`erlang:process_info/2`
See:
- uwiger/edown#23
- erlang/otp#7576

Signed-off-by: Paul Guyot <pguyot@kallisys.net>
pguyot added a commit to pguyot/AtomVM that referenced this issue Aug 26, 2023
Also narrow type specification of `erlang:process_info/2`
Also update edown with a patch to fix crash when parsing updated doc for
`erlang:process_info/2`
See:
- uwiger/edown#23
- erlang/otp#7576

Signed-off-by: Paul Guyot <pguyot@kallisys.net>
pguyot added a commit to pguyot/AtomVM that referenced this issue Aug 27, 2023
Also narrow type specification of `erlang:process_info/2`
Also update edown with a patch to fix crash when parsing updated doc for
`erlang:process_info/2`
See:
- uwiger/edown#23
- erlang/otp#7576

Signed-off-by: Paul Guyot <pguyot@kallisys.net>
pguyot added a commit to pguyot/AtomVM that referenced this issue Aug 28, 2023
Also narrow type specification of `erlang:process_info/2`
Also update edown with a patch to fix crash when parsing updated doc for
`erlang:process_info/2`
See:
- uwiger/edown#23
- erlang/otp#7576

Signed-off-by: Paul Guyot <pguyot@kallisys.net>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug Issue is reported as a bug team:VM Assigned to OTP team VM
Projects
None yet
Development

No branches or pull requests

3 participants