edoc/LSP question

[Olivier Boudeville]

Hi,

I need to (ab)use the including of header files in order to define a
fixed set of (accessor-like) functions that shall be available from
within a group of modules, so that these functions can be used in such
modules directly (locally, i.e. without adding any module prefix when
calling them from these modules).

The code works great but I would like the @doc documentation of these
functions to appear in the generated API and, more importantly, through
the Erlang Language Server [https://erlang-ls.github.io/], which would
be very useful when editing these modules.

edoc detects these functions and generates HTML entries for them (iff
adding the {preprocess, true} option), but I never managed to have their
@doc comments show up there; and the LS server does not seem to take
them into account either.

Following minimal test with OTP 24 was done:

* in mytest.erl:

%% @doc Simple test.
-module(mytest).

-export([f/0, foobar/0]).

-include("mytest.hrl").

%% @doc Doc for f.
f() ->
    ok.

* in mytest.hrl:

%% @doc Doc for foobar.
foobar() ->
    ok.

* command line to generate HTML: erl -noshell -run edoc_run file
'"mytest.erl"' '[{dir,"."},{preprocess, true}]'

No amount of: %% @headerfile "mytest.hrl" seems to be of help either:
that header file is parsed, foobar/0 is listed in the HTML but its @doc
is lacking.

Is there a way to have at least the LS server be aware of these @doc tags?

Thanks in advance for any hint!

Best regards,

Olivier.

[Michael Truog]

Post by Olivier Boudeville
Hi,
I need to (ab)use the including of header files in order to define a
fixed set of (accessor-like) functions that shall be available from
within a group of modules, so that these functions can be used in such
modules directly (locally, i.e. without adding any module prefix when
calling them from these modules).
functions to appear in the generated API and, more importantly,
through the Erlang Language Server [https://erlang-ls.github.io/],
which would be very useful when editing these modules.
edoc detects these functions and generates HTML entries for them (iff
adding the {preprocess, true} option), but I never managed to have
take them into account either.

Hi Olivier,

I think you may find a script like mine helpful because I believe I ran
into a similar problem:
https://github.com/okeuday/trie/blob/master/generate_docs.sh

Best Regards,
Michael