Adopt ExDoc & Move Documentation In-Tree

.gitignore

@@ -25,3 +25,4 @@ env
 
 # hex_core artifact
 apps/rebar/src/vendored/r3_safe_erl_term.erl
+apps/rebar/doc

README.md

@@ -61,21 +61,21 @@ This list presents the known working version combos between Rebar3 and
 Erlang/OTP. Always use the latest version your project can tolerate for latest
 security fixes.
 
-| Rebar3 | Erlang/OTP Support Range | Notes
-|-       |-      | -
-| 3.25.1 | 26-28 | issues with newer Windows versions were reported on 3.25.0 and OTP-28
-| 3.24.0 | 25-27 |
-| 3.23.0 | 25-27 |
-| 3.22.1 | 25-27 |
-| 3.21.0 | 24-26 |
-| 3.20.0 | 23-25 |
-| 3.19.0 | 23-25 |
-| 3.18.0 | 22-24 |
-| 3.17.0 | 22-24 |
-| 3.16.1 | 22-24 | Don't use 3.16.0, see https://ferd.ca/you-ve-got-to-upgrade-rebar3.html
-| 3.15.2 | 19-23 | Don't use 3.15.0 or 3.15.1, see https://ferd.ca/you-ve-got-to-upgrade-rebar3.html
-| 3.14.1 | 19-23 |
-| 3.13.3 | 19-22 | Don't use 3.13.1 or 3.13.2, see https://ferd.ca/you-ve-got-to-upgrade-rebar3.html
+| Rebar3 | Erlang/OTP Support Range | Notes |
+|-       |-      | - |
+| 3.25.1 | 26-28 | issues with newer Windows versions were reported on 3.25.0 and OTP-28 |
+| 3.24.0 | 25-27 | |
+| 3.23.0 | 25-27 | |
+| 3.22.1 | 25-27 | |
+| 3.21.0 | 24-26 | |
+| 3.20.0 | 23-25 | |
+| 3.19.0 | 23-25 | |
+| 3.18.0 | 22-24 | |
+| 3.17.0 | 22-24 | |
+| 3.16.1 | 22-24 | Don't use 3.16.0, see https://ferd.ca/you-ve-got-to-upgrade-rebar3.html |
+| 3.15.2 | 19-23 | Don't use 3.15.0 or 3.15.1, see https://ferd.ca/you-ve-got-to-upgrade-rebar3.html |
+| 3.14.1 | 19-23 | |
+| 3.13.3 | 19-22 | Don't use 3.13.1 or 3.13.2, see https://ferd.ca/you-ve-got-to-upgrade-rebar3.html |
 
 A [getting started guide is maintained on the official documentation website](https://rebar3.org/docs/getting-started),
 but installing rebar3 can be done by any of the ways described below
@@ -139,7 +139,7 @@ others via the plugin ecosystem:
 | Code Coverage        | Various commands can be instrumented to accumulate code coverage data (such as `eunit` or `ct`). Reports can be generated with `rebar3 cover` |
 | Common Test          | The test framework can be run by calling `rebar3 ct` |
 | Dependencies         | Rebar3 maintains local copies of dependencies on a per-project basis. They are fetched deterministically, can be locked, upgraded, fetched from source, packages, or from local directories. See [Dependencies on the documentation website](https://rebar3.org/docs/configuration/dependencies/). Call `rebar3 tree` to show the whole dependency tree. |
-| Documentation        | Print help for rebar3 itself (`rebar3 help`) or for a specific task (`rebar3 help <task>`). Full reference at [rebar3.org](https://rebar3.org/docs). |
+| Documentation        | Print help for rebar3 itself (`rebar3 help`) or for a specific task (`rebar3 help <task>`). Full reference at [rebar3 documentation](https://rebar3.org/docs). |
 | Dialyzer             | Run the Dialyzer analyzer on the project with `rebar3 dialyzer`. Base PLTs for each version of the language will be cached and reused for faster analysis |
 | Edoc                 | Generate documentation using edoc with `rebar3 edoc` |
 | Escript generation   | Rebar3 can be used to generate [escripts](http://www.erlang.org/doc/man/escript.html) providing an easy way to run all your applications on a system where Erlang is installed |
@@ -188,6 +188,6 @@ For bug reports, roadmaps, and issues, visit the [github issues
 page](https://github.com/erlang/rebar3/issues).
 
 General rebar community resources and links can be found at
-[rebar3.org/docs/about/about-us/#community](https://rebar3.org/docs/about/about-us/#community)
+[Community | About Us](https://rebar3.org/docs/about/about-us/#community)
 
-To contribute to rebar3, please refer to [CONTRIBUTING](CONTRIBUTING.md).
+To contribute to rebar3, please refer to [CONTRIBUTING](https://github.com/erlang/rebar3/blob/master/CONTRIBUTING.md).

apps/rebar/src/cth_fail_fast.erl

@@ -1,4 +1,5 @@
 -module(cth_fail_fast).
+-moduledoc false.
 
 %% Callbacks
 -export([id/1]).

apps/rebar/src/cth_retry.erl

@@ -1,4 +1,5 @@
 -module(cth_retry).
+-moduledoc false.
 
 %% Callbacks
 -export([id/1]).

apps/rebar/src/r3.erl

@@ -1,6 +1,7 @@
 %%% @doc external alias for `rebar_agent' for more convenient
 %%% calls from a shell.
 -module(r3).
+-moduledoc false.
 -export([do/1, do/2, do/3, async_do/1, async_do/2, async_do/3, break/0, resume/0]).
 -export(['$handle_undefined_function'/2]).
 -include("rebar.hrl").

apps/rebar/src/rebar3.erl

@@ -35,6 +35,7 @@
 %% accessible to the rest of the run.
 %% @end
 -module(rebar3).
+-moduledoc false.
 
 -export([main/0,
          main/1,

apps/rebar/src/rebar_agent.erl

@@ -1,6 +1,7 @@
 %%% @doc Runs a process that holds a rebar3 state and can be used
 %%% to statefully maintain loaded project state into a running VM.
 -module(rebar_agent).
+-moduledoc false.
 -export([start_link/1, do/1, do/2, do/3, async_do/1, async_do/2, async_do/3]).
 -export(['$handle_undefined_function'/2]).
 -export([init/1,
@@ -290,9 +291,9 @@ reload_modules(Modules0) ->
     Modules = [M || M <- Modules0, is_changed(M)],
     reload_modules(Modules, erlang:function_exported(code, prepare_loading, 1)).
 
-%% @spec is_changed(atom()) -> boolean()
 %% @doc true if the loaded module is a beam with a vsn attribute
 %%      and does not match the on-disk beam file, returns false otherwise.
+-spec is_changed(atom()) -> boolean().
 is_changed(M) ->
     try
         module_vsn(M:module_info(attributes)) =/= module_vsn(code:get_object_code(M))

apps/rebar/src/rebar_app_discover.erl

@@ -1,6 +1,7 @@
 %%% @doc utility functions to do the basic discovery of apps
 %%% and layout for the project.
 -module(rebar_app_discover).
+-moduledoc false.
 
 -export([do/2,
          format_error/1,

apps/rebar/src/rebar_app_utils.erl

@@ -25,6 +25,7 @@
 %% THE SOFTWARE.
 %% -------------------------------------------------------------------
 -module(rebar_app_utils).
+-moduledoc false.
 
 -export([find/2,
          find/3,

apps/rebar/src/rebar_compiler.erl

@@ -1,4 +1,5 @@
 -module(rebar_compiler).
+-moduledoc false.
 
 -export([analyze_all/2,
          analyze_all_extras/2,

apps/rebar/src/rebar_compiler_dag.erl

@@ -1,6 +1,7 @@
 %%% Module handling the directed graph required for the analysis
 %%% of all top-level applications by the various compiler plugins.
 -module(rebar_compiler_dag).
+-moduledoc false.
 -export([init/4, status/4, maybe_store/5, terminate/1]).
 -export([prune/5, populate_sources/5, populate_deps/3, propagate_stamps/1,
          compile_order/4, store_artifact/4]).

apps/rebar/src/rebar_compiler_epp.erl

@@ -3,6 +3,7 @@
 %%% build complete and accurate DAGs
 %%% @end
 -module(rebar_compiler_epp).
+-moduledoc false.
 -export([deps/2, resolve_module/2]).
 %% cache (a la code path storage, but for dependencies not in code path)
 -export([ensure_started/0, flush/0, resolve_source/2]).

apps/rebar/src/rebar_compiler_erl.erl

@@ -1,4 +1,5 @@
 -module(rebar_compiler_erl).
+-moduledoc false.
 
 -behaviour(rebar_compiler).
 

apps/rebar/src/rebar_compiler_format.erl

@@ -1,5 +1,6 @@
 %%% @doc Module handling rich formatting of errors.
 -module(rebar_compiler_format).
+-moduledoc false.
 -export([format/5]).
 
 -include("rebar.hrl").

apps/rebar/src/rebar_compiler_mib.erl

@@ -1,4 +1,5 @@
 -module(rebar_compiler_mib).
+-moduledoc false.
 
 -behaviour(rebar_compiler).
 

apps/rebar/src/rebar_compiler_xrl.erl

@@ -1,4 +1,5 @@
 -module(rebar_compiler_xrl).
+-moduledoc false.
 
 -behaviour(rebar_compiler).
 

apps/rebar/src/rebar_compiler_yrl.erl

@@ -1,4 +1,5 @@
 -module(rebar_compiler_yrl).
+-moduledoc false.
 
 -behaviour(rebar_compiler).
 

apps/rebar/src/rebar_completion.erl

@@ -1,4 +1,5 @@
 -module(rebar_completion).
+-moduledoc false.
 
 -export([generate/2]).
 

apps/rebar/src/rebar_completion_bash.erl

@@ -1,6 +1,7 @@
 %% @doc Completion file generator for bash
 %% @end
 -module(rebar_completion_bash).
+-moduledoc false.
 
 -behavior(rebar_completion).
 

apps/rebar/src/rebar_completion_zsh.erl

@@ -1,6 +1,7 @@
 %% @doc Completion file generator for zsh
 %% @end
 -module(rebar_completion_zsh).
+-moduledoc false.
 
 -behavior(rebar_completion).
 

apps/rebar/src/rebar_config.erl

@@ -25,6 +25,7 @@
 %% THE SOFTWARE.
 %% -------------------------------------------------------------------
 -module(rebar_config).
+-moduledoc false.
 
 -export([consult_root/0
         ,consult/1

apps/rebar/src/rebar_core.erl

@@ -27,6 +27,7 @@
 %% @doc Module providing core functionality about command dispatch, namespacing,
 %% and chaining for rebar3.
 -module(rebar_core).
+-moduledoc false.
 
 -export([init_command/2, process_namespace/2, process_command/2, do/2, format_error/1]).
 

apps/rebar/src/rebar_dialyzer_format.erl

@@ -13,6 +13,7 @@
 %%%          the 'red vs green' resambles the diff view 'remove vs add'
 %%% * blue:  argument positions.
 -module(rebar_dialyzer_format).
+-moduledoc false.
 
 -include("rebar.hrl").
 

apps/rebar/src/rebar_digraph.erl

@@ -1,6 +1,7 @@
 %%% @doc build a digraph of applications in order to figure out dependency
 %%% and compile order.
 -module(rebar_digraph).
+-moduledoc false.
 
 -export([compile_order/1
         ,restore_graph/1

apps/rebar/src/rebar_dist_utils.erl

@@ -1,6 +1,7 @@
 %%% Common functions to boot/stop distributed setups for
 %%% the rebar3 script.
 -module(rebar_dist_utils).
+-moduledoc false.
 -export([either/3, short/2, long/2, find_options/1]).
 -include("rebar.hrl").
 

apps/rebar/src/rebar_env.erl

@@ -1,4 +1,5 @@
 -module(rebar_env).
+-moduledoc false.
 
 -export([create_env/1,
          create_env/2]).

apps/rebar/src/rebar_erlc_compiler.erl

@@ -25,6 +25,7 @@
 %% THE SOFTWARE.
 %% -------------------------------------------------------------------
 -module(rebar_erlc_compiler).
+-moduledoc false.
 
 -export([compile/1, compile/2, compile/3,
          compile_dir/3, compile_dir/4,

apps/rebar/src/rebar_fetch.erl

@@ -6,6 +6,7 @@
 %%
 %% -------------------------------------------------------------------
 -module(rebar_fetch).
+-moduledoc false.
 
 -export([lock_source/2,
          download_source/2,

apps/rebar/src/rebar_file_utils.erl

@@ -25,6 +25,7 @@
 %% THE SOFTWARE.
 %% -------------------------------------------------------------------
 -module(rebar_file_utils).
+-moduledoc false.
 
 -export([try_consult/1,
          consult_config/2,
@@ -86,7 +87,7 @@ consult_config(State, Filename) ->
     consult_config_terms(State, Config).
 
 %% @doc Reads a config file via consult_env_config/2 if the file name has
-%% the suffix `.src`, and with consult_config/2 otherwise
+%% the suffix `.src', and with consult_config/2 otherwise
 -spec consult_any_config(rebar_state:t(), file:filename()) -> [[tuple()]].
 consult_any_config(State, Filename) ->
     case is_src_config(Filename) of

apps/rebar/src/rebar_git_resource.erl

@@ -1,6 +1,7 @@
 %% -*- erlang-indent-level: 4;indent-tabs-mode: nil -*-
 %% ex: ts=4 sw=4 et
 -module(rebar_git_resource).
+-moduledoc false.
 
 -behaviour(rebar_resource_v2).
 

apps/rebar/src/rebar_git_subdir_resource.erl

@@ -1,6 +1,7 @@
 %% -*- erlang-indent-level: 4;indent-tabs-mode: nil -*-
 %% ex: ts=4 sw=4 et
 -module(rebar_git_subdir_resource).
+-moduledoc false.
 
 -behaviour(rebar_resource_v2).
 

apps/rebar/src/rebar_hex_repos.erl

@@ -1,4 +1,5 @@
 -module(rebar_hex_repos).
+-moduledoc false.
 
 -export([from_state/2,
          get_repo_config/2,

apps/rebar/src/rebar_hg_resource.erl

@@ -1,6 +1,7 @@
 %% -*- erlang-indent-level: 4;indent-tabs-mode: nil -*-
 %% ex: ts=4 sw=4 et
 -module(rebar_hg_resource).
+-moduledoc false.
 
 -behaviour(rebar_resource_v2).
 

apps/rebar/src/rebar_hooks.erl

@@ -1,4 +1,5 @@
 -module(rebar_hooks).
+-moduledoc false.
 
 -export([run_all_hooks/5
         ,run_all_hooks/6

apps/rebar/src/rebar_httpc_adapter.erl

@@ -1,6 +1,7 @@
 %% Derived from hex_core v0.7.1 for extra flexibility.
 
 -module(rebar_httpc_adapter).
+-moduledoc false.
 -behaviour(r3_hex_http).
 -export([request/5]).
 

apps/rebar/src/rebar_log.erl

@@ -25,6 +25,7 @@
 %% THE SOFTWARE.
 %% -------------------------------------------------------------------
 -module(rebar_log).
+-moduledoc false.
 
 -export([init/2,
          crashdump/2,

apps/rebar/src/rebar_opts.erl

@@ -1,4 +1,5 @@
 -module(rebar_opts).
+-moduledoc false.
 
 -export([get/2,
          get/3,

apps/rebar/src/rebar_otp_app.erl

@@ -25,6 +25,7 @@
 %% THE SOFTWARE.
 %% -------------------------------------------------------------------
 -module(rebar_otp_app).
+-moduledoc false.
 
 -export([compile/2,
          format_error/1]).

apps/rebar/src/rebar_packages.erl

@@ -1,4 +1,5 @@
 -module(rebar_packages).
+-moduledoc false.
 
 -export([get/2
         ,get_all_names/1

apps/rebar/src/rebar_parallel.erl

@@ -11,6 +11,7 @@
 %%% without demanding to know all the tasks to run ahead of time.
 %%% @end
 -module(rebar_parallel).
+-moduledoc false.
 -export([queue/5,
          pool/4, pool/5, pool_task_async/2, pool_terminate/1]).
 -include("rebar.hrl").

apps/rebar/src/rebar_pkg_resource.erl

@@ -1,6 +1,7 @@
 %% -*- erlang-indent-level: 4;indent-tabs-mode: nil -*-
 %% ex: ts=4 sw=4 et
 -module(rebar_pkg_resource).
+-moduledoc false.
 
 -behaviour(rebar_resource_v2).
 

apps/rebar/src/rebar_plugins.erl

@@ -2,6 +2,7 @@
 %% ex: ts=4 sw=4 et
 
 -module(rebar_plugins).
+-moduledoc false.
 
 -export([project_plugins_install/1
         ,top_level_install/1

apps/rebar/src/rebar_prv_alias.erl

@@ -5,6 +5,7 @@
 %%% from a plugin at https://github.com/tsloughter/rebar_alias after
 %%% years of stability. Only some error checks were added
 -module(rebar_prv_alias).
+-moduledoc false.
 
 -behaviour(provider).
 

apps/rebar/src/rebar_prv_app_discovery.erl

@@ -2,6 +2,7 @@
 %% ex: ts=4 sw=4 et
 
 -module(rebar_prv_app_discovery).
+-moduledoc false.
 
 -behaviour(provider).
 

apps/rebar/src/rebar_prv_as.erl

@@ -2,6 +2,7 @@
 %% ex: ts=4 sw=4 et
 
 -module(rebar_prv_as).
+-moduledoc false.
 
 -behaviour(provider).