Edoc diagnostics (erlang-ls#1213)

* Import edoc_report module from OTP

* Fix include, indent file

* Add support for edoc diagnostics

* Only produce edoc for OTP 24

The priv directory contains some intentional broken edocs, but early versions of edoc try to generate edoc for those, too

.github/workflows/build.yml

@@ -72,6 +72,7 @@ jobs:
  run: rebar3 do cover, coveralls send
  - name: Produce Documentation
  run: rebar3 edoc
+ if: ${{ matrix.otp-version == '24' }}
  - name: Publish Documentation
  uses: actions/upload-artifact@v2
  with:

apps/els_lsp/priv/code_navigation/src/edoc_diagnostics.erl

@@ -0,0 +1,15 @@
+-module(edoc_diagnostics).
+
+-export([main/0]).
+
+%% @edoc Main function
+main() ->
+ internal().
+
+%% @docc internal
+internal() ->
+ ok.
+
+%% @doc `
+unused() ->
+ ok.

apps/els_lsp/src/edoc_report.erl

@@ -0,0 +1,122 @@
+%% =============================================================================
+%% An erlang_ls fork of Erlang/OTP's edoc_report
+%% =============================================================================
+%% The main reasons for the fork:
+%% * The edoc application does not offer an API to return a
+%% list of warnings and errors
+%% =====================================================================
+%% Licensed under the Apache License, Version 2.0 (the "License"); you may
+%% not use this file except in compliance with the License. You may obtain
+%% a copy of the License at <https://www.apache.org/licenses/LICENSE-2.0>
+%%
+%% Unless required by applicable law or agreed to in writing, software
+%% distributed under the License is distributed on an "AS IS" BASIS,
+%% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+%% See the License for the specific language governing permissions and
+%% limitations under the License.
+%%
+%% Alternatively, you may use this file under the terms of the GNU Lesser
+%% General Public License (the "LGPL") as published by the Free Software
+%% Foundation; either version 2.1, or (at your option) any later version.
+%% If you wish to allow use of your version of this file only under the
+%% terms of the LGPL, you should delete the provisions above and replace
+%% them with the notice and other provisions required by the LGPL; see
+%% <https://www.gnu.org/licenses/>. If you do not delete the provisions
+%% above, a recipient may use your version of this file under the terms of
+%% either the Apache License or the LGPL.
+%%
+%% @private
+%% @copyright 2001-2003 Richard Carlsson
+%% @author Richard Carlsson <[email protected]>
+%% @see edoc
+%% @end
+%% =====================================================================
+
+%% @doc EDoc verbosity/error reporting.
+
+-module(edoc_report).
+
+-compile({no_auto_import, [error/1, error/2, error/3]}).
+-export([error/1,
+ error/2,
+ error/3,
+ report/2,
+ report/3,
+ report/4,
+ warning/1,
+ warning/2,
+ warning/3,
+ warning/4]).
+
+-type where() :: any().
+-type what() :: any().
+-type line() :: non_neg_integer().
+-type severity() :: warning | error.
+
+-include_lib("edoc/src/edoc.hrl").
+
+-define(DICT_KEY, edoc_diagnostics).
+
+-spec error(what()) -> ok.
+error(What) ->
+ error([], What).
+
+-spec error(where(), what()) -> ok.
+error(Where, What) ->
+ error(0, Where, What).
+
+-spec error(line(), where(), any()) -> ok.
+error(Line, Where, S) when is_list(S) ->
+ report(Line, Where, S, [], error);
+error(Line, Where, {S, D}) when is_list(S) ->
+ report(Line, Where, S, D, error);
+error(Line, Where, {format_error, M, D}) ->
+ report(Line, Where, M:format_error(D), [], error).
+
+-spec warning(string()) -> ok.
+warning(S) ->
+ warning(S, []).
+
+-spec warning(string(), [any()]) -> ok.
+warning(S, Vs) ->
+ warning([], S, Vs).
+
+-spec warning(where(), string(), [any()]) -> ok.
+warning(Where, S, Vs) ->
+ warning(0, Where, S, Vs).
+
+-spec warning(line(), where(), string(), [any()]) -> ok.
+warning(L, Where, S, Vs) ->
+ report(L, Where, S, Vs, warning).
+
+-spec report(string(), [any()]) -> ok.
+report(S, Vs) ->
+ report([], S, Vs).
+
+-spec report(where(), string(), [any()]) -> ok.
+report(Where, S, Vs) ->
+ report(0, Where, S, Vs).
+
+-spec report(line(), where(), string(), [any()]) -> ok.
+report(L, Where, S, Vs) ->
+ report(L, Where, S, Vs, error).
+
+-spec report(line(), where(), string(), [any()], severity()) -> ok.
+report(L, Where, S, Vs, Severity) ->
+ put(?DICT_KEY, [{L, where(Where), S, Vs, Severity}|get(?DICT_KEY)]).
+
+-spec where([any()] |
+ {string(), module | footer | header | {atom(), non_neg_integer()}})
+ -> string().
+where({File, module}) ->
+ io_lib:fwrite("~ts, in module header: ", [File]);
+where({File, footer}) ->
+ io_lib:fwrite("~ts, in module footer: ", [File]);
+where({File, header}) ->
+ io_lib:fwrite("~ts, in header file: ", [File]);
+where({File, {F, A}}) ->
+ io_lib:fwrite("~ts, function ~ts/~w: ", [File, F, A]);
+where([]) ->
+ io_lib:fwrite("~s: ", [?APPLICATION]);
+where(File) when is_list(File) ->
+ File ++ ": ".

apps/els_lsp/src/els_diagnostics.erl

@@ -61,6 +61,7 @@ available_diagnostics() ->
  , <<"compiler">>
  , <<"crossref">>
  , <<"dialyzer">>
+ , <<"edoc">>
  , <<"gradualizer">>
  , <<"elvis">>
  , <<"unused_includes">>

apps/els_lsp/src/els_edoc_diagnostics.erl

@@ -0,0 +1,93 @@
+%%==============================================================================
+%% Edoc diagnostics
+%%==============================================================================
+-module(els_edoc_diagnostics).
+
+%%==============================================================================
+%% Behaviours
+%%==============================================================================
+-behaviour(els_diagnostics).
+
+%%==============================================================================
+%% Exports
+%%==============================================================================
+-export([ is_default/0
+ , run/1
+ , source/0
+ ]).
+
+%%==============================================================================
+%% Includes
+%%==============================================================================
+-include("els_lsp.hrl").
+
+%%==============================================================================
+%% Callback Functions
+%%==============================================================================
+
+-spec is_default() -> boolean().
+is_default() ->
+ false.
+
+%% The edoc application currently does not offer an API to
+%% programmatically return a list of warnings and errors. Instead,
+%% it simply outputs the warnings and errors to the standard
+%% output.
+%% We created an issue for the OTP team to address this:
+%% https://github.com/erlang-ls/erlang_ls/issues/384
+%% Meanwhile, hackity-hack!
+%% Let's override the reporting module for edoc (edoc_report)
+%% and (ab)use the process dictionary to collect the list of
+%% warnings and errors.
+-spec run(uri()) -> [els_diagnostics:diagnostic()].
+run(Uri) ->
+ Paths = [els_utils:to_list(els_uri:path(Uri))],
+ Fun = fun(Dir) ->
+ Options = edoc_options(Dir),
+ put(edoc_diagnostics, []),
+ try
+ edoc:run(Paths, Options)
+ catch
+ _:_:_ ->
+ ok
+ end,
+ [make_diagnostic(L, Format, Args, Severity) ||
+ {L, _Where, Format, Args, Severity}
+ <- get(edoc_diagnostics), L =/= 0]
+ end,
+ tempdir:mktmp(Fun).
+
+-spec source() -> binary().
+source() ->
+ <<"Edoc">>.
+
+%%==============================================================================
+%% Internal Functions
+%%==============================================================================
+-spec edoc_options(string()) -> proplists:proplist().
+edoc_options(Dir) ->
+ Macros = [{N, V} || {'d', N, V} <- els_compiler_diagnostics:macro_options()],
+ Includes = [I || {i, I} <- els_compiler_diagnostics:include_options()],
+ [ {preprocess, true}
+ , {macros, Macros}
+ , {includes, Includes}
+ , {dir, Dir}
+ ].
+
+-spec make_diagnostic(pos_integer(), string(), [any()], warning | error) ->
+ els_diagnostics:diagnostic().
+make_diagnostic(Line, Format, Args, Severity0) ->
+ Severity = severity(Severity0),
+ Message = els_utils:to_binary(io_lib:format(Format, Args)),
+ els_diagnostics:make_diagnostic( els_protocol:range(#{ from => {Line, 1}
+ , to => {Line + 1, 1}
+ })
+ , Message
+ , Severity
+ , source()).
+
+-spec severity(warning | error) -> els_diagnostics:severity().
+severity(warning) ->
+ ?DIAGNOSTIC_WARNING;
+severity(error) ->
+ ?DIAGNOSTIC_ERROR.

apps/els_lsp/src/els_lsp.app.src

@@ -6,6 +6,7 @@
  {applications, [
  kernel,
  stdlib,
+ edoc,
  docsh,
  elvis_core,
  rebar3_format,

apps/els_lsp/test/els_diagnostics_SUITE.erl

@@ -43,6 +43,7 @@
  , gradualizer/1
  , module_name_check/1
  , module_name_check_whitespace/1
+ , edoc_main/1
  ]).
 
 %%==============================================================================
@@ -125,6 +126,11 @@ init_per_testcase(TestCase, Config) when TestCase =:= gradualizer ->
  meck:expect(els_gradualizer_diagnostics, is_default, 0, true),
  els_mock_diagnostics:setup(),
  els_test_utils:init_per_testcase(TestCase, Config);
+init_per_testcase(TestCase, Config) when TestCase =:= edoc_main ->
+ meck:new(els_edoc_diagnostics, [passthrough, no_link]),
+ meck:expect(els_edoc_diagnostics, is_default, 0, true),
+ els_mock_diagnostics:setup(),
+ els_test_utils:init_per_testcase(TestCase, Config);
 init_per_testcase(TestCase, Config) ->
  els_mock_diagnostics:setup(),
  els_test_utils:init_per_testcase(TestCase, Config).
@@ -166,6 +172,11 @@ end_per_testcase(TestCase, Config) when TestCase =:= gradualizer ->
  els_test_utils:end_per_testcase(TestCase, Config),
  els_mock_diagnostics:teardown(),
  ok;
+end_per_testcase(TestCase, Config) when TestCase =:= edoc_main ->
+ meck:unload(els_edoc_diagnostics),
+ els_test_utils:end_per_testcase(TestCase, Config),
+ els_mock_diagnostics:teardown(),
+ ok;
 end_per_testcase(TestCase, Config) ->
  els_test_utils:end_per_testcase(TestCase, Config),
  els_mock_diagnostics:teardown(),
@@ -679,6 +690,26 @@ module_name_check_whitespace(_Config) ->
  Hints = [],
  els_test:run_diagnostics_test(Path, Source, Errors, Warnings, Hints).
 
+-spec edoc_main(config()) -> ok.
+edoc_main(_Config) ->
+ Path = src_path("edoc_diagnostics.erl"),
+ Source = <<"Edoc">>,
+ Errors = [ #{ message => <<"`-quote ended unexpectedly at line 13">>
+ , range => {{12, 0}, {13, 0}}
+ }
+ ],
+ Warnings = [ #{ message =>
+ <<"tag @edoc not recognized.">>
+ , range => {{4, 0}, {5, 0}}
+ }
+ , #{ message =>
+ <<"tag @docc not recognized.">>
+ , range => {{8, 0}, {9, 0}}
+ }
+ ],
+ Hints = [],
+ els_test:run_diagnostics_test(Path, Source, Errors, Warnings, Hints).
+
 %%==============================================================================
 %% Internal Functions
 %%==============================================================================

apps/els_lsp/test/els_test.erl

@@ -79,7 +79,9 @@ assert_diagnostics(Source, Expected, Diagnostics, Severity) ->
  Filtered = [D || #{severity := S} = D <- Diagnostics, S =:= Severity],
  Simplified = [simplify_diagnostic(D) || D <- Filtered],
  FixedExpected = [maybe_fix_range(Source, D) || D <- Expected],
- ?assertEqual(FixedExpected, Simplified, Filtered).
+ ?assertEqual(lists:sort(FixedExpected),
+ lists:sort(Simplified),
+ Filtered).
 
 -spec simplify_diagnostic(els_diagnostics:diagnostic()) ->
  simplified_diagnostic().

elvis.config

@@ -34,6 +34,7 @@
  , els_tcp
  , els_dap_test_utils
  , els_test_utils
+ , edoc_report
  ]}}
  , {elvis_text_style, line_length, #{limit => 80, skip_comments => false}}
  , {elvis_style, operator_spaces, #{ rules => [ {right, ","}