stdlib: add type specs to shell docs

adds type specifications to shell_docs. allows users to type `ht(ssh, daemon)` and get the documentation together with the spec. the types shown are those included in the `beam_lib:chunks`, which currently shows some types that are not exported by needed by functions. these types are the same ones shown on the online docs. the shell_docs_SUITE.erl has been parallelised due to the amount of time taken to render the new documentation. the reason is that we need parse the debug_info from a beam file, where we previously were not doing this and thus, not showing the type information.
erlang · Sep 20, 2024 · 9fab3e7 · 9fab3e7
1 parent 00a67d7
commit 9fab3e7
Show file tree

Hide file tree

Showing 523 changed files with 12,085 additions and 14,329 deletions.
diff --git a/lib/stdlib/src/shell_docs.erl b/lib/stdlib/src/shell_docs.erl
diff --git a/lib/stdlib/test/shell_docs_SUITE.erl b/lib/stdlib/test/shell_docs_SUITE.erl
@@ -17,7 +17,10 @@
 %%
 %% %CopyrightEnd%
 %%
+
 -module(shell_docs_SUITE).
+-moduledoc false.
+
 -export([all/0, suite/0, groups/0, init_per_suite/1, end_per_suite/1,
    init_per_group/2, end_per_group/2]).
 
@@ -26,6 +29,8 @@
 
 -export([render_all/1, update_render/0, update_render/1]).
 
+-export([execute/3]).
+
 -include_lib("kernel/include/eep48.hrl").
 -include_lib("stdlib/include/assert.hrl").
 
@@ -122,14 +127,14 @@ update_render(DataDir) ->
 render_smoke(_Config) ->
     docsmap(
       fun(Mod, #docs_v1{ docs = Docs } = D) ->
-              lists:foreach(
+              E = fun({error,_}) ->
+                          ok;
+                     (Doc) ->
+                          unicode:characters_to_binary(Doc)
+                  end,
+              pmap(
                 fun(Config) ->
                         try
-                            E = fun({error,_}) ->
-                                        ok;
-                                   (Doc) ->
-                                        unicode:characters_to_binary(Doc)
-                                end,
                             E(shell_docs:render(Mod, D, Config)),
                             E(shell_docs:render_type(Mod, D, Config)),
                             E(shell_docs:render_callback(Mod, D, Config)),
@@ -166,16 +171,50 @@ render_smoke(_Config) ->
                                 io:format("Failed to render ~p~n~p:~p~n",[Mod,R,ST]),
                                 exit(R)
                         end
-                end, [#{},
-                      #{ ansi => false },
-                      #{ ansi => true },
-                      #{ columns => 5 },
-                      #{ columns => 150 },
-                      #{ encoding => unicode },
-                      #{ encoding => latin1 }])
+                end, format_configurations())
       end),
     ok.
 
+docsmap(Fun) ->
+  F = fun F({Mod,_,_}) ->
+            F(Mod);
+          F(Mod) when is_list(Mod) ->
+            F(list_to_atom(Mod));
+          F(Mod) ->
+            case code:get_doc(Mod) of
+              {error, missing} ->
+                ok;
+              {error, cover_compiled} ->
+                ok;
+              {error, E} when E =:= eperm; E =:= eacces; E =:= eio ->
+                %% This can happen in BSD's for some reason...
+                ok;
+              {error, eisdir} ->
+                %% Uhm?
+                ok;
+              {ok, Docs} ->
+                try
+                  _ = Fun(Mod, Docs),
+                  {ok, self(), Mod}
+                catch E:R:ST ->
+                    io:format("Failed to render ~p~n~p:~p:~p~n",[Mod,E,R,ST]),
+                    erlang:raise(E,R,ST)
+                end
+            end
+      end,
+  pmap(F, code:all_available()),
+  ok.
+
+
+format_configurations() ->
+  [#{},
+   #{ ansi => false },
+   #{ ansi => true },
+   #{ columns => 5 },
+   #{ columns => 150 },
+   #{ encoding => unicode },
+   #{ encoding => latin1 }].
+
 markdown_to_shelldoc(#docs_v1{format = Format}=Docs) ->
     DefaultFormat = <<"text/markdown">>,
     DFormat = binary_to_list(DefaultFormat),
@@ -376,30 +415,35 @@ sanitize(FName) ->
       end, FName, [{"/","slash"},{":","colon"},
                    {"\\*","star"},{"<","lt"},{">","gt"},{"=","eq"}]).
 
-docsmap(Fun) ->
-    lists:map(
-      fun F({Mod,_,_}) ->
-              F(Mod);
-          F(Mod) when is_list(Mod) ->
-              F(list_to_atom(Mod));
-          F(Mod) ->
-              case code:get_doc(Mod) of
-                  {error, missing} ->
-                      ok;
-                  {error, cover_compiled} ->
-                      ok;
-                  {error, E} when E =:= eperm; E =:= eacces; E =:= eio ->
-                      %% This can happen in BSD's for some reason...
-                      ok;
-                  {error, eisdir} ->
-                      %% Uhm?
-                      ok;
-                  {ok, Docs} ->
-                      try
-                          Fun(Mod, Docs)
-                      catch E:R:ST ->
-                              io:format("Failed to render ~p~n~p:~p:~p~n",[Mod,E,R,ST]),
-                              erlang:raise(E,R,ST)
-                      end
-              end
-      end, code:all_available()).
+%%
+%% Parallel map function.
+%%
+%% Parallel map function that discards the result of the function
+%% `F` applied to each of the items in `Ls`. It spawns as many
+%% processes as items there are in `Ls`. If the list is large,
+%% consider adding a set of working processes that round-robin on
+%% the job to do be done.
+%%
+%% - `F` is the function to perform
+%% - `Ls` the list of items to iterate on
+%%
+pmap(F, Ls) when is_function(F),
+                 is_list(Ls) ->
+  _ = lists:foreach(fun(Config) ->
+                        spawn_link(?MODULE, execute,[Config, F, self()])
+                   end, Ls),
+  ResponseCounter = length(Ls),
+  ok = sync(ResponseCounter),
+  ok.
+
+execute(Item, F, Pid) ->
+  _ = F(Item),
+  Pid ! ok.
+
+sync(0) ->
+  ok;
+sync(N) ->
+  receive
+    ok ->
+      sync(N-1)
+  end.
diff --git a/lib/stdlib/test/shell_docs_SUITE_data/erlang.docs_v1 b/lib/stdlib/test/shell_docs_SUITE_data/erlang.docs_v1
diff --git a/lib/stdlib/test/shell_docs_SUITE_data/file.docs_v1 b/lib/stdlib/test/shell_docs_SUITE_data/file.docs_v1
diff --git a/lib/stdlib/test/shell_docs_SUITE_data/kernel_file.txt b/lib/stdlib/test/shell_docs_SUITE_data/kernel_file.txt
@@ -5,7 +5,8 @@
 
   This module provides an interface to the file system.
 
-  Warning:
+  [;;4mWarning[0m
+
     File operations are only guaranteed to appear atomic when
     going through the same file server. A NIF or other OS process
     may observe intermediate steps on certain operations on some
@@ -50,7 +51,8 @@
   See also section Notes About Raw Filenames in the STDLIB User's
   Guide.
 
-  Note:
+  [;;4mNote[0m
+
     File operations used to accept filenames containing null
     characters (integer value zero). This caused the name to be
     truncated and in some cases arguments to primitive operations
@@ -136,7 +138,8 @@
   another node, or if the file server runs as slave to the file
   server of another node, also binaries are copied.
 
-  Note:
+  [;;4mNote[0m
+
     Raw files use the file system of the host machine of the node.
     For normal files (non-raw), the file server is used to find
     the files, and if the node is running its file server as slave
@@ -190,12 +193,13 @@
   contents of the binaries without copying the data at all, except
   for perhaps deep down in the operating system kernel.
 
-  Warning:
+  [;;4mWarning[0m
+
     If an error occurs when accessing an open file with module [;;4mio[0m,
     the process handling the file exits. The dead file process can
     hang if a process tries to access it later. This will be fixed
     in a future release.
 
 [;1mSee Also[0m
 
-  [;;4mfilename(3)[0m
+  [;;4mfilename[0m
diff --git a/lib/stdlib/test/shell_docs_SUITE_data/kernel_file_advise_4_func.txt b/lib/stdlib/test/shell_docs_SUITE_data/kernel_file_advise_4_func.txt
@@ -10,11 +10,6 @@
 [;;4mSince[0m:
   OTP R14B
 
-  Types:
-    -type posix_file_advise() ::
-          normal | sequential | random | no_reuse | will_need |
-          dont_need.
-
   [;;4madvise/4[0m can be used to announce an intention to access file data
   in a specific pattern in the future, thus allowing the operating
   system to perform appropriate optimizations.

diff --git a/lib/stdlib/test/shell_docs_SUITE_data/kernel_file_altname_1_func.txt b/lib/stdlib/test/shell_docs_SUITE_data/kernel_file_altname_1_func.txt
@@ -1,5 +1,5 @@
 
-[;1m  altname/1[0m
+  [;1m-spec altname(Name :: name_all()) -> any().[0m
 
   The documentation for altname/1 is hidden. This probably means
   that it is internal and not to be used by other applications.
diff --git a/lib/stdlib/test/shell_docs_SUITE_data/kernel_file_consult_1_func.txt b/lib/stdlib/test/shell_docs_SUITE_data/kernel_file_consult_1_func.txt
@@ -10,20 +10,19 @@
   [;1m                          Mod :: module(),[0m
   [;1m                          Term :: term()}.[0m
 
-  Reads Erlang terms, separated by '.', from [;;4mFilename[0m. Returns one
+  Reads Erlang terms, separated by [;;4m.[0m, from [;;4mFilename[0m. Returns one
   of the following:
 
-  [;;4m[;;4m{ok, Terms}[0m[0m:
-    The file was successfully read.
+   • [;;4m{ok, Terms}[0m - The file was successfully read.
 
-  [;;4m[;;4m{error, atom()}[0m[0m:
-    An error occurred when opening the file or reading it. For a
-    list of typical error codes, see [;;4mopen/2[0m.
+   • [;;4m{error, atom()}[0m - An error occurred when opening the file
+     or reading it. For a list of typical error codes, see [;;4m[0m
+     [;;4mopen/2[0m.
 
-  [;;4m[;;4m{error, {Line, Mod, Term}}[0m[0m:
-    An error occurred when interpreting the Erlang terms in the
-    file. To convert the three-element tuple to an English
-    description of the error, use [;;4mformat_error/1[0m.
+   • [;;4m{error, {Line, Mod, Term}}[0m - An error occurred when
+     interpreting the Erlang terms in the file. To convert the
+     three-element tuple to an English description of the error,
+     use [;;4mformat_error/1[0m.
 
   Example:
 
@@ -34,4 +33,4 @@
     {ok,[{person,"kalle",25},{person,"pelle",30}]}
 
   The encoding of [;;4mFilename[0m can be set by a comment, as described
-  in [;;4mepp(3)[0m.
+  in [;;4mepp[0m.
diff --git a/lib/stdlib/test/shell_docs_SUITE_data/kernel_file_copy_3_func.txt b/lib/stdlib/test/shell_docs_SUITE_data/kernel_file_copy_3_func.txt
@@ -13,8 +13,7 @@
 
   Copies [;;4mByteCount[0m bytes from [;;4mSource[0m to [;;4mDestination[0m. [;;4mSource[0m
   and [;;4mDestination[0m refer to either filenames or IO devices from,
-  for example, [;;4mopen/2[0m. [;;4mByteCount[0m defaults to [;;4minfinity[0m,
-  denoting an infinite number of bytes.
+  for example, [;;4mopen/2[0m.
 
   Argument [;;4mModes[0m is a list of possible modes, see [;;4mopen/2[0m, and
   defaults to [;;4m[][0m.

diff --git a/lib/stdlib/test/shell_docs_SUITE_data/kernel_file_copy_func.txt b/lib/stdlib/test/shell_docs_SUITE_data/kernel_file_copy_func.txt
@@ -9,32 +9,7 @@
   [;1m                  BytesCopied :: non_neg_integer(),[0m
   [;1m                  Reason :: posix() | badarg | terminated.[0m
 
-  Copies [;;4mByteCount[0m bytes from [;;4mSource[0m to [;;4mDestination[0m. [;;4mSource[0m
-  and [;;4mDestination[0m refer to either filenames or IO devices from,
-  for example, [;;4mopen/2[0m. [;;4mByteCount[0m defaults to [;;4minfinity[0m,
-  denoting an infinite number of bytes.
-
-  Argument [;;4mModes[0m is a list of possible modes, see [;;4mopen/2[0m, and
-  defaults to [;;4m[][0m.
-
-  If both [;;4mSource[0m and [;;4mDestination[0m refer to filenames, the files
-  are opened with [;;4m[read, binary][0m and [;;4m[write, binary][0m prepended
-  to their mode lists, respectively, to optimize the copy.
-
-  If [;;4mSource[0m refers to a filename, it is opened with [;;4mread[0m mode
-  prepended to the mode list before the copy, and closed when done.
-
-  If [;;4mDestination[0m refers to a filename, it is opened with [;;4mwrite[0m
-  mode prepended to the mode list before the copy, and closed when
-  done.
-
-  Returns [;;4m{ok, BytesCopied}[0m, where [;;4mBytesCopied[0m is the number of
-  bytes that was copied, which can be less than [;;4mByteCount[0m if end
-  of file was encountered on the source. If the operation fails, [;;4m[0m
-  [;;4m{error, Reason}[0m is returned.
-
-  Typical error reasons: as for [;;4mopen/2[0m if a file had to be opened,
-  and as for [;;4mread/2[0m and [;;4mwrite/2[0m.
+  There is no documentation for copy(Source, Destination, infinity)
 
   [;1m-spec copy(Source, Destination, ByteCount) ->[0m
   [;1m              {ok, BytesCopied} | {error, Reason}[0m
@@ -50,8 +25,7 @@
 
   Copies [;;4mByteCount[0m bytes from [;;4mSource[0m to [;;4mDestination[0m. [;;4mSource[0m
   and [;;4mDestination[0m refer to either filenames or IO devices from,
-  for example, [;;4mopen/2[0m. [;;4mByteCount[0m defaults to [;;4minfinity[0m,
-  denoting an infinite number of bytes.
+  for example, [;;4mopen/2[0m.
 
   Argument [;;4mModes[0m is a list of possible modes, see [;;4mopen/2[0m, and
   defaults to [;;4m[][0m.

diff --git a/lib/stdlib/test/shell_docs_SUITE_data/kernel_file_del_dir_1_func.txt b/lib/stdlib/test/shell_docs_SUITE_data/kernel_file_del_dir_1_func.txt
@@ -7,20 +7,15 @@
 
   Typical error reasons:
 
-  [;;4m[;;4meacces[0m[0m:
-    Missing search or write permissions for the parent directories
-    of [;;4mDir[0m.
+   • [;;4meacces[0m - Missing search or write permissions for the parent
+     directories of [;;4mDir[0m.
 
-  [;;4m[;;4meexist[0m[0m:
-    The directory is not empty.
+   • [;;4meexist[0m - The directory is not empty.
 
-  [;;4m[;;4menoent[0m[0m:
-    The directory does not exist.
+   • [;;4menoent[0m - The directory does not exist.
 
-  [;;4m[;;4menotdir[0m[0m:
-    A component of [;;4mDir[0m is not a directory. On some platforms, [;;4m[0m
-    [;;4menoent[0m is returned instead.
+   • [;;4menotdir[0m - A component of [;;4mDir[0m is not a directory. On some
+     platforms, [;;4menoent[0m is returned instead.
 
-  [;;4m[;;4meinval[0m[0m:
-    Attempt to delete the current directory. On some platforms, [;;4m[0m
-    [;;4meacces[0m is returned instead.
+   • [;;4meinval[0m - Attempt to delete the current directory. On some
+     platforms, [;;4meacces[0m is returned instead.
diff --git a/lib/stdlib/test/shell_docs_SUITE_data/kernel_file_del_dir_r_1_func.txt b/lib/stdlib/test/shell_docs_SUITE_data/kernel_file_del_dir_r_1_func.txt
@@ -8,11 +8,9 @@
   Deletes file or directory [;;4mFile[0m. If [;;4mFile[0m is a directory, its
   contents is first recursively deleted. Returns:
 
-  [;;4m[;;4mok[0m[0m:
-    The operation completed without errors.
+   • [;;4mok[0m - The operation completed without errors.
 
-  [;;4m[;;4m{error, posix()}[0m[0m:
-    An error occurred when accessing or deleting [;;4mFile[0m. If some
-    file or directory under [;;4mFile[0m could not be deleted, [;;4mFile[0m
-    cannot be deleted as it is non-empty, and [;;4m{error, eexist}[0m is
-    returned.
+   • [;;4m{error, posix()}[0m - An error occurred when accessing or
+     deleting [;;4mFile[0m. If some file or directory under [;;4mFile[0m
+     could not be deleted, [;;4mFile[0m cannot be deleted as it is
+     non-empty, and [;;4m{error, eexist}[0m is returned.