Document rebar_compiler behaviour

[lpil]

The new rebar_compiler behaviour is the recommended way to teach rebar to compile new file types, but use of the behaviour is non-obvious.

It would be great to get some documentation (such as comments on the behaviour callbacks

rebar3/src/rebar_compiler.erl

Lines 17 to 24 in 311ee6b

	-callback context(rebar_app_info:t()) -> #{src_dirs => [file:dirname()],
	include_dirs => [file:dirname()],
	src_ext => extension(),
	out_mappings => out_mappings()}.
	-callback needed_files(digraph:graph(), [file:filename()], rebar_app_info:t()) -> [file:filename()].
	-callback dependencies(file:filename(), file:dirname(), [file:dirname()]) -> [file:filename()].
	-callback compile(file:filename(), out_mappings(), rebar_dict(), list()) ->
	ok | {ok, [string()]} | {ok, [string()], [string()]}.

) so that it's clearer how to make use of it :)

[ferd]

Right. There might be a small change to the needed_files/3 callback (becomes needed_files/4) so it should be documented soon, when we cut 3.7.0 final; we've been using the release candidates to find a few bugs in the API and avoid committing to backwards compat on what could be unstable code, so we avoided documenting it so far.

[ferd]

See #1938 for the pending PR changing the callback

[lpil]

Thank you!

[ferd]

I've added initial documentation at https://www.rebar3.org/v3/docs/custom-compiler-modules