diff options
author | Lukas Larsson <lukas@erlang.org> | 2021-11-01 09:09:16 +0100 |
---|---|---|
committer | GitHub <noreply@github.com> | 2021-11-01 09:09:16 +0100 |
commit | 03d9930f6d23e890ebf3ce9b375620fe46a447fa (patch) | |
tree | b1cf809f5cdc1a3bd1ba11d9f89590f8fa948940 /lib/edoc | |
parent | dc1e498fe8ada82ac7f5d1d236523e34f172bd35 (diff) | |
parent | 26c78d18921a75e46d63ffe9060cd576d21813d9 (diff) | |
download | erlang-03d9930f6d23e890ebf3ce9b375620fe46a447fa.tar.gz |
Merge pull request #5205 from erszcz/edoc-chunk-module-visibility/OTP-17733
EDoc: Adjust default/private/hidden doc visibility in chunks
Diffstat (limited to 'lib/edoc')
-rw-r--r-- | lib/edoc/src/edoc_doclet_chunks.erl | 16 | ||||
-rw-r--r-- | 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}. |