Merge pull request #7502 from garazdawi/lukas/stdlib/fix-shell-docs-multi-clause/OTP-18683

Fix shell docs multi clause

Author: garazdawi

lib/stdlib/src/shell_docs.erl

@@ -595,13 +595,18 @@ render_function(FDocs, D, Config) when is_map(Config) ->
 render_function(FDocs, #docs_v1{ docs = Docs } = D, Config) ->
     Grouping =
         lists:foldl(
-          fun({_Group,_Anno,_Sig,_Doc,#{ equiv := Group }} = Func,Acc) ->
-                  Members = maps:get(Group, Acc, []),
-                  Acc#{ Group => [Func|Members] };
+          fun({_Group,_Anno,_Sig,_Doc,#{ equiv := Group }} = Func, Acc) ->
+                  case lists:keytake(Group, 1, Acc) of
+                      false -> [{Group, [Func]} | Acc];
+                      {value, {Group, Members}, NewAcc} ->
+                          [{Group,[Func|Members]} | NewAcc]
+                  end;
              ({Group, _Anno, _Sig, _Doc, _Meta} = Func, Acc) ->
-                  Members = maps:get(Group, Acc, []),
-                  Acc#{ Group => [Func|Members] }
-          end, #{}, lists:sort(FDocs)),
+                  [{Group, [Func]} | Acc]
+          end, [],
+          %% We sort only on the group element, so that multiple entries with
+          %% the same group do not change order. For example erlang:halt/1.
+          lists:sort(fun(A, B) -> element(1, A) =< element(1, B) end, FDocs)),
     lists:map(
       fun({Group,Members}) ->
               Signatures = lists:flatmap(fun render_signature/1, lists:reverse(Members)),
@@ -621,7 +626,7 @@ render_function(FDocs, #docs_v1{ docs = Docs } = D, Config) ->
                                 Signatures, get_local_doc(Group, Doc, D), D, Config)
                       end
               end
-      end, maps:to_list(Grouping)).
+      end, lists:reverse(Grouping)).
 
 %% Render the signature of either function, type, or anything else really.
 render_signature({{_Type,_F,_A},_Anno,_Sigs,_Docs,#{ signature := Specs } = Meta}) ->

lib/stdlib/test/shell_docs_SUITE_data/erlang.docs_v1

@@ -120,7 +120,7 @@
 
    • estale - Stale remote file handle
 
-   • exdev - Cross-domain link
+   • exdev - Cross-device link
 
 Performance
 

lib/stdlib/test/shell_docs_SUITE_data/file.docs_v1

@@ -1,4 +1,4 @@
 
-  -type fd() :: #file_descriptor{}.
+  fd()
 
   A file descriptor representing a file opened in raw mode.

lib/stdlib/test/shell_docs_SUITE_data/kernel_file.txt

@@ -6,7 +6,7 @@
              Delay :: non_neg_integer()} |
             delayed_write |
             {read_ahead, Size :: pos_integer()} |
-            read_ahead | compressed |
+            read_ahead | compressed | compressed_one |
             {encoding, unicode:encoding()} |
             sync.
 

lib/stdlib/test/shell_docs_SUITE_data/kernel_file_fd_0_type.txt

@@ -113,6 +113,10 @@
     read_file_info/1 does probably not match the number of bytes
     that can be read from a compressed file.
 
+  compressed_one:
+    Read one member of a gzip compressed file. Option 
+    compressed_one can only be combined with read.
+
   {encoding, Encoding}:
     Makes the file perform automatic translation of characters to
     and from a specific (Unicode) encoding. Notice that the data

lib/stdlib/test/shell_docs_SUITE_data/kernel_file_mode_0_type.txt

@@ -2,6 +2,14 @@
   -spec pid2name(Pid) -> {ok, Filename} | undefined
                     when Filename :: filename_all(), Pid :: pid().
 
+Deprecated:
+  file:pid2name/1 is deprecated and will be removed in OTP 27; this
+  functionality is no longer supported
+
+  Change:
+    This function is deprecated and will be removed in Erlang/OTP
+    27.
+
   If Pid is an I/O device, that is, a pid returned from open/2,
   this function returns the filename, or rather:
 

lib/stdlib/test/shell_docs_SUITE_data/kernel_file_open_2_func.txt

@@ -4,7 +4,7 @@ These types are documented in this module:
 
   -type deep_list() :: [char() | atom() | deep_list()].
 
-  -type fd() :: #file_descriptor{}.
+  fd()
 
   -type filename() :: string().
 
@@ -45,7 +45,7 @@ These types are documented in this module:
              Delay :: non_neg_integer()} |
             delayed_write |
             {read_ahead, Size :: pos_integer()} |
-            read_ahead | compressed |
+            read_ahead | compressed | compressed_one |
             {encoding, unicode:encoding()} |
             sync.
 

lib/stdlib/test/shell_docs_SUITE_data/kernel_file_pid2name_1_func.txt

@@ -0,0 +1,6 @@
+
+  callback_mode/0
+
+  The documentation for callback_mode/0 is hidden. This probably
+  means that it is internal and not to be used by other
+  applications.