Improve documentation

CONTRIBUTING.md

@@ -79,6 +79,10 @@ Rebar3 is an escript built around the concept of providers. Providers are the
 modules that do the work to fulfill a user's command. They are documented in
 [the official documentation website](http://www.rebar3.org/docs/plugins#section-provider-interface).
 
+> [!NOTE]
+> The Rebar3 repository uses an [umbrella project structure](https://rebar3.org/docs/basic_usage/).
+> Paths shown here are relative to the directory `apps/rebar`.
+
 Example provider:
 
 ```erlang
@@ -121,7 +125,7 @@ format_error(Reason) ->
     io_lib:format("~p", [Reason]).
 ```
 
-Providers are then listed in `rebar.app.src`, and can be called from
+Providers are then listed in `rebar.app.src.script`, and can be called from
 the command line or as a programmatical API.
 
 All commands are therefore implemented in standalone modules. If you call
@@ -218,6 +222,7 @@ be any of:
 {ok, OKRes}
 {ok, OKRes, ProfilesUsed}
 {error, Reason}
+return
 
 % where:
 ProfilesUsed :: string() % matching the profiles to validate (defaults to "*")

apps/rebar/test/rebar_test_utils.erl

@@ -37,9 +37,19 @@ init_rebar_state(Config, Name) ->
     [{apps, AppsDir}, {checkouts, CheckoutsDir}, {state, State} | Config].
 
 %% @doc Takes common test config, a rebar config ([] if empty), a command to
-%% run ("install_deps", "compile", etc.), and a list of expected applications
-%% and/or dependencies to be present, and verifies whether they are all in
-%% place.
+%% run ("install_deps", "compile", etc.), and the expected term to check.
+%%
+%% The expected term can be one of
+%%
+%% - `{ok, ExpectationList}`: The expectation list is matched in the manner
+%%   described below, using "*" for the profile.
+%% - `{ok, ExpectationList, ProfileUsed}`: The expectation list is matched
+%%   in the manner described below for the given profile.
+%% - `{error, Reason}`: We assert that the error matches the expected reason.
+%% - `return`: No assertion is made.
+%%
+%% The expectation list is a list of expected applications and/or dependencies
+%% to be present, and verifies whether they are all in place.
 %%
 %% The expectation list takes elements of the form:
 %% - `{app, Name :: string()}': checks that the app is properly built.
@@ -49,6 +59,7 @@ init_rebar_state(Config, Name) ->
 %%   has been fetched, and that a given version has been chosen. Useful to
 %%   test for conflict resolution. Also ignores the build status of the
 %%   dependency.
+%% - See `CONTRIBUTING.md` for more.
 %%
 %% This function assumes `init_rebar_state/1-2' has run before, in order to
 %% fetch the `apps' and `state' values from the CT config.

bootstrap

@@ -52,7 +52,7 @@ main(Args) ->
     %% Build rebar3 modules with compile:file
     bootstrap_rebar3(),
 
-    %% Build rebar.app from rebar.app.src
+    %% Build rebar.app from rebar.app.src.script
     {ok, App} = rebar_app_info:new(rebar, "3.25.1", filename:absname("_build/default/lib/rebar/")),
     rebar_otp_app:compile(rebar_state:new(), App),