Add support for custom EDoc tags (erlang-ls#1243)

apps/els_core/src/els_config.erl

@@ -55,7 +55,8 @@
  | elvis_config_path
  | indexing_enabled
  | bsp_enabled
- | compiler_telemetry_enabled.
+ | compiler_telemetry_enabled
+ | edoc_custom_tags.
 
 -type path() :: file:filename().
 -type state() :: #{ apps_dirs => [path()]
@@ -132,6 +133,7 @@ do_initialize(RootUri, Capabilities, InitOptions, {ConfigPath, Config}) ->
  IncrementalSync = maps:get("incremental_sync", Config, true),
  CompilerTelemetryEnabled
  = maps:get("compiler_telemetry_enabled", Config, false),
+ EDocCustomTags = maps:get("edoc_custom_tags", Config, []),
 
  IndexingEnabled = maps:get(<<"indexingEnabled">>, InitOptions, true),
 
@@ -155,6 +157,7 @@ do_initialize(RootUri, Capabilities, InitOptions, {ConfigPath, Config}) ->
  ok = set(elvis_config_path, ElvisConfigPath),
  ok = set(bsp_enabled, BSPEnabled),
  ok = set(compiler_telemetry_enabled, CompilerTelemetryEnabled),
+ ok = set(edoc_custom_tags, EDocCustomTags),
  ok = set(incremental_sync, IncrementalSync),
  %% Calculated from the above
  ok = set(apps_paths , project_paths(RootPath, AppsDirs, false)),

apps/els_lsp/priv/code_navigation/erlang_ls.config

@@ -2,3 +2,6 @@ macros:
  - name: DEFINED_WITHOUT_VALUE
  - name: DEFINED_WITH_VALUE
  value: 1
+edoc_custom_tags:
+ - edoc
+ - generated

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

@@ -2,7 +2,7 @@
 
 -export([main/0]).
 
-%% @edoc Main function
+%% @mydoc Main function
 main() ->
  internal().
 

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

@@ -0,0 +1,18 @@
+-module(edoc_diagnostics_custom_tags).
+
+-export([ a/0 ]).
+
+%% @edoc
+%% `edoc' is a custom alias for `doc'
+a() ->
+ ok.
+
+%% @docc
+%% `docc' is not an existing or custom tag
+b() ->
+ ok.
+
+%% @generated
+%% The `generated' tag is used for generated code
+c() ->
+ ok.

apps/els_lsp/src/edoc_report.erl

@@ -4,6 +4,7 @@
 %% The main reasons for the fork:
 %% * The edoc application does not offer an API to return a
 %% list of warnings and errors
+%% * Support for custom EDoc tags
 %% =====================================================================
 %% 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
@@ -85,6 +86,14 @@ warning(Where, S, Vs) ->
  warning(0, Where, S, Vs).
 
 -spec warning(line(), where(), string(), [any()]) -> ok.
+warning(L, Where, "tag @~s not recognized." = S, [Tag] = Vs) ->
+ CustomTags = els_config:get(edoc_custom_tags),
+ case lists:member(atom_to_list(Tag), CustomTags) of
+ true ->
+ ok;
+ false ->
+ report(L, Where, S, Vs, warning)
+ end;
 warning(L, Where, S, Vs) ->
  report(L, Where, S, Vs, warning).
 

apps/els_lsp/test/els_diagnostics_SUITE.erl

@@ -45,6 +45,7 @@
  , module_name_check_whitespace/1
  , edoc_main/1
  , edoc_skip_app_src/1
+ , edoc_custom_tags/1
  ]).
 
 %%==============================================================================
@@ -128,7 +129,8 @@ init_per_testcase(TestCase, Config) when TestCase =:= gradualizer ->
  els_mock_diagnostics:setup(),
  els_test_utils:init_per_testcase(TestCase, Config);
 init_per_testcase(TestCase, Config) when TestCase =:= edoc_main;
- TestCase =:= edoc_skip_app_src ->
+ TestCase =:= edoc_skip_app_src;
+ TestCase =:= edoc_custom_tags ->
  meck:new(els_edoc_diagnostics, [passthrough, no_link]),
  meck:expect(els_edoc_diagnostics, is_default, 0, true),
  els_mock_diagnostics:setup(),
@@ -175,7 +177,8 @@ end_per_testcase(TestCase, Config) when TestCase =:= gradualizer ->
  els_mock_diagnostics:teardown(),
  ok;
 end_per_testcase(TestCase, Config) when TestCase =:= edoc_main;
- TestCase =:= edoc_skip_app_src ->
+ TestCase =:= edoc_skip_app_src;
+ TestCase =:= edoc_custom_tags ->
  meck:unload(els_edoc_diagnostics),
  els_test_utils:end_per_testcase(TestCase, Config),
  els_mock_diagnostics:teardown(),
@@ -708,7 +711,7 @@ edoc_main(_Config) ->
  }
  ],
  Warnings = [ #{ message =>
- <<"tag @edoc not recognized.">>
+ <<"tag @mydoc not recognized.">>
  , range => {{4, 0}, {5, 0}}
  }
  , #{ message =>
@@ -719,7 +722,7 @@ edoc_main(_Config) ->
  Hints = [],
  els_test:run_diagnostics_test(Path, Source, Errors, Warnings, Hints).
 
- -spec edoc_skip_app_src(config()) -> ok.
+-spec edoc_skip_app_src(config()) -> ok.
 edoc_skip_app_src(_Config) ->
  Path = src_path("code_navigation.app.src"),
  Source = <<"Edoc">>,
@@ -728,6 +731,20 @@ edoc_skip_app_src(_Config) ->
  Hints = [],
  els_test:run_diagnostics_test(Path, Source, Errors, Warnings, Hints).
 
+-spec edoc_custom_tags(config()) -> ok.
+edoc_custom_tags(_Config) ->
+ %% Custom tags are defined in priv/code_navigation/erlang_ls.config
+ Path = src_path("edoc_diagnostics_custom_tags.erl"),
+ Source = <<"Edoc">>,
+ Errors = [],
+ Warnings = [ #{ message =>
+ <<"tag @docc not recognized.">>
+ , range => {{9, 0}, {10, 0}}
+ }
+ ],
+ Hints = [],
+ els_test:run_diagnostics_test(Path, Source, Errors, Warnings, Hints).
+
 %%==============================================================================
 %% Internal Functions
 %%==============================================================================