File 0137-Adjust-default-private-hidden-doc-visibili... of Package erlang

Overview Repositories Revisions Requests Users Attributes Meta

File 0137-Adjust-default-private-hidden-doc-visibility-in-chun.patch of Package erlang

From 26c78d18921a75e46d63ffe9060cd576d21813d9 Mon Sep 17 00:00:00 2001
From: Radek Szymczyszyn <radoslaw.szymczyszyn@erlang-solutions.com>
Date: Fri, 17 Sep 2021 09:00:23 +0200
Subject: [PATCH] Adjust default/private/hidden doc visibility in chunks

Prior to these adjustments when using ExDoc to generate docs for
Erlang projects modules were required to have some top-level docs to be
listed in the generated HTML. They could still have function-level docs,
but the module wouldn't be listed anyway, so these docs wouldn't be accessible.

With these changes a module will be listed even if it does not have
top-level docs, so that its function docs are available in the generated HTML.
This means a module has to be explicitly marked with EDoc @private or
@hidden not to be listed.

See also https://github.com/elixir-lang/ex_doc/issues/1393.
---
 lib/edoc/src/edoc_doclet_chunks.erl | 16 ++++++++++------
 lib/edoc/src/edoc_layout_chunks.erl | 21 +++++++++++++--------
 2 files changed, 23 insertions(+), 14 deletions(-)

diff --git a/lib/edoc/src/edoc_doclet_chunks.erl b/lib/edoc/src/edoc_doclet_chunks.erl
index 50eb4086b6..d619df2f0a 100644
--- a/lib/edoc/src/edoc_doclet_chunks.erl
+++ b/lib/edoc/src/edoc_doclet_chunks.erl
@@ -89,11 +89,8 @@ gen(Sources, _App, Modules, Ctxt) ->
 
 sources(Sources, Dir, Modules, Env, Options) ->
     Suffix = proplists:get_value(file_suffix, Options, ?DEFAULT_FILE_SUFFIX),
-    Private = proplists:get_bool(private, Options),
-    Hidden = proplists:get_bool(hidden, Options),
     {Ms, E} = lists:foldl(fun (Src, {Set, Error}) ->
-				  source(Src, Dir, Suffix, Env, Set,
-					 Private, Hidden, Error, Options)
+				  source(Src, Dir, Suffix, Env, Set, Error, Options)
 			  end,
 			  {sets:new(), false}, Sources),
     {[M || M <- Modules, sets:is_element(M, Ms)], E}.
@@ -104,10 +101,17 @@ sources(Sources, Dir, Modules, Env, Options) ->
 %% Add its name to the set if it was successful.
 %% Errors are just flagged at this stage,
 %% allowing all source files to be processed even if some of them fail.
-source({_M, Name, Path}, Dir, Suffix, Env, OkSet, _Private, _Hidden, ErrorFlag, Options) ->
+source({_M, Name, Path}, Dir, Suffix, Env, OkSet, ErrorFlag, Options0) ->
     File = filename:join(Path, Name),
     try
-	{_Module, Doc, Entries} = edoc:get_doc(File, Env, [return_entries, private, hidden | Options]),
+	%% Without these opts the entries returned by EDoc core (`edoc_extract:source1/5') won't have
+	%% all the necessary data to generate chunks.
+	RequiredChunkOpts = [return_entries, private, hidden],
+	%% But we also want to have the real user-defined `private' accessible.
+	Options = ([{show_private, proplists:get_bool(private, Options0)}]
+		   ++ RequiredChunkOpts
+		   ++ Options0),
+	{_Module, Doc, Entries} = edoc:get_doc(File, Env, Options),
 	Chunk = edoc:layout(Doc, [{entries, Entries}, {source, Name} | Options]),
 	WriteOptions = [{encoding, utf8}],
 	ok = write_file(Chunk, Dir, chunk_file_name(Name, Suffix), WriteOptions),
diff --git a/lib/edoc/src/edoc_layout_chunks.erl b/lib/edoc/src/edoc_layout_chunks.erl
index 927b85bf07..e325346b56 100644
--- a/lib/edoc/src/edoc_layout_chunks.erl
+++ b/lib/edoc/src/edoc_layout_chunks.erl
@@ -135,23 +135,28 @@ edoc_to_chunk(Doc, Opts) ->
       Opts :: proplists:proplist().
 doc_contents(XPath, Doc, Opts) ->
     case doc_visibility(XPath, Doc, Opts) of
-	hidden -> hidden;
 	none -> none;
-	regular -> doc_contents_(XPath, Doc, Opts)
+	hidden -> hidden;
+	show -> doc_contents_(XPath, Doc, Opts)
     end.
 
+-spec doc_visibility(_, _, _) -> none | hidden | show.
 doc_visibility(_XPath, Doc, Opts) ->
     case {xpath_to_text("./@private", Doc, Opts),
+	  proplists:get_bool(show_private, Opts),
 	  xpath_to_text("./@hidden", Doc, Opts)}
     of
-	{<<"yes">>, _} ->
-	    %% EDoc `@private' is EEP-48 `hidden'
+	%% Generating `@private' documentation was explicitly requested
+	{<<"yes">>, true, _} ->
+	    show;
+	%% EDoc `@private' maps to EEP-48 `hidden'
+	{<<"yes">>, _, _} ->
 	    hidden;
-	{_, <<"yes">>} ->
-	    %% EDoc `@hidden' is EEP-48 `none'
+	%% EDoc `@hidden' is EEP-48 `none'
+	{_, _, <<"yes">>} ->
 	    none;
 	_ ->
-	    regular
+	    show
     end.
 
 doc_contents_(_XPath, Doc, Opts) ->
@@ -449,7 +454,7 @@ source_file(Opts) ->
     Source.
 
 -spec doc_content(_, _) -> doc().
-doc_content([], _Opts) -> none;
+doc_content([], _Opts) -> #{};
 doc_content(Content, Opts) ->
     DocLanguage = proplists:get_value(lang, Opts, <<"en">>),
     #{DocLanguage => Content}.
-- 
2.31.1

Places

File 0137-Adjust-default-private-hidden-doc-visibility-in-chun.patch of Package erlang

Places