Why is the documentation I write missing from my types? (OTP25, rebar3_ex_doc)

weaver · February 14, 2025, 4:55pm

Hi there!

I’m generating documentation for a project written in OTP 25, and I’m trying to document my -type attributes. I’ve tried several different approaches (%% @doc before, %% on the same line, and %% after the -type declaration. None of them work.)

Erlang 25 uses the %% syntax to document types just fine, and it renders in the edocs just fine.

Is it that edoc reads these comments directly from the file when generating, but it doesn’t make it into the documentation chunks used by rebar3_ex_doc? I’ve tried to look at the documentation chunk directly with code:get_doc/1 and I don’t see the documentation there.

zhongwencool · February 15, 2025, 4:26am

%% @doc it works perfectly for me on OTP 27.

code

github.com/zhongwencool/ecron

src/ecron.erl

main


      
          %% @doc
          %% Adds a new crontab job with specified parameters. Jobs exceeding their limits are automatically removed.
          %%
          %% Parameters:
          %% <ul>
          %%   <li>`Register' - The process name where the job will be registered</li>
          %%   <li>`JobName' - Unique identifier for the job. Returns `{error, already_exist}' if duplicate</li>
          %%   <li>`Spec' - Crontab expression defining execution schedule</li>
          %%   <li>`MFA' - `{Module, Function, Args}' to execute when triggered</li>
          %%   <li>`Start' - Start time `{Hour,Min,Sec}' or `unlimited' for immediate start</li>
          %%   <li>`End' - End time `{Hour,Min,Sec}' or `unlimited' for no end</li>
          %%   <li>`Opts' - Options list:
          %%     <ul>
          %%       <li>`{singleton, boolean()}' - If true (default), prevents concurrent execution</li>
          %%       <li>`{max_count, pos_integer() | unlimited}' - Maximum executions allowed</li>
          %%     </ul>
          %%   </li>
          %% </ul>
          %%
          %% Returns: `{ok, JobName}' | `{error, already_exist}' | `{error, parse_error(), term()}'

document view：

https://hexdocs.pm/ecron/ecron.html#add/7

rebar.config

github.com/zhongwencool/ecron

rebar.config

main


      
          {hex, [
              {doc, #{provider => ex_doc}}
          ]}.
          
          {ex_doc, [
              {extras, [
                  {"README.md", #{title => "Overview"}},
          
                  {"telemetry.md", #{title => "Telemetry"}},
                  {"global.md", #{title => "Cluster Task"}},
                  {"CHANGELOG.md", #{title => "Changelog"}},
                  {"LICENSE", #{title => "License"}}
              ]},
              {main, "README.md"},
              {homepage_url, "https://github.com/zhongwencool/ecron"},
              {source_url, "https://github.com/zhongwencool/ecron"},
              {api_reference, false},
              {with_mermaid, true}
          ]}.

weaver · February 15, 2025, 2:09pm

Thanks for this example, but it doesn’t apply to my issue. To clarify, I’m having issues documenting the -type attribute, not the -spec attribute. So something like this:

-type type_name() :: string().
%% Documentation for the above type.

zhongwencool · February 22, 2025, 11:49am

Sorry, I tried, but ‘type’ doesn’t work either.

starbelly · February 22, 2025, 4:34pm

Hi

I maintain rebar3_ex_doc. I can not replicate your issue with the following, could you provide an example source code (I know you provided a snippet). Also, what versions exactly are you using for both OTP 25 and rebar3_ex_doc?

To note, rebar3_ex_doc is mostly a simple plugin, where edoc and ex_doc do the real work.

Below is an example I used to test :

-module(footran).

-type grunt_file() :: string().
%% The mess we're in.

-export_type([grunt_file/0]).

-export([the_mess_we_are_in/1]).

-spec the_mess_we_are_in(grunt_file()) -> ok.
the_mess_we_are_in(Str) ->
    io:put_chars(Str).