Unexpected blank line after %% @private

[paulo-ferraz-oliveira]

I usually write my edoc related "tag" like so

-spec resolve(Module :: module(), Host :: dispatcher:host()) ->
                 {ok, [inet:ip_address()]}.
%% @private
resolve(Module, Host) ->
    Module:resolve(Host).

This is getting formatted to

-spec resolve(Module :: module(), Host :: dispatcher:host()) ->
                 {ok, [inet:ip_address()]}.
%% @private

resolve(Module, Host) ->
    Module:resolve(Host).

Is seems like a bug, but I'm not sure.

[elbrujohalcon]

Definitely a bug.

[elbrujohalcon]

Although… Why do you put your edoc comments after the spec… WHY????

[paulo-ferraz-oliveira]

WHY????

I imagined that, some years after starting to write Erlang, I'd come across a formatting tool whose developers I really wanted to annoy 😄.

On a serious note, I'll try to find a reference as to why I started doing this. I didn't start this by myself; I remember I saw it somewhere.

[paulo-ferraz-oliveira]

If it's of any consolation, erlfmt suffered from a similar bug. 😄

[elbrujohalcon]

Yeah, I know.

[paulo-ferraz-oliveira]

Another example found in the wild: https://github.com/g-andrade/aequitas/blob/master/src/aequitas_category.erl#L176.

[paulo-ferraz-oliveira]

But my source was most surely something more widely used like lager.

[elbrujohalcon]

Oh, man! Specs with parentheses!! 🙈

[paulo-ferraz-oliveira]

😄 long live diversity...

What about specs as comments?

I'm sure you're not surprised; you've seen much more that I have while working on the tool, for sure...

[paulo-ferraz-oliveira]

In any case, I wouldn't mind (let me know if I should open a new issue) that the tool moved comments from "between the spec and the function" to "above the spec", like so...

This

-spec resolve(Module :: module(), Host :: dispatcher:host()) ->
                 {ok, [inet:ip_address()]}.
%% @private
resolve(Module, Host) ->
    Module:resolve(Host).

would become

%% @private
-spec resolve(Module :: module(), Host :: dispatcher:host()) ->
                 {ok, [inet:ip_address()]}.
resolve(Module, Host) ->
    Module:resolve(Host).

[elbrujohalcon]

😄 long live diversity...

What about specs as comments?

I'm sure you're not surprised; you've seen much more that I have while working on the tool, for sure...

Yeah… that's ye ould edoc style…

[elbrujohalcon]

In any case, I wouldn't mind (let me know if I should open a new issue) that the tool moved comments from "between the spec and the function" to "above the spec", like so...

This

-spec resolve(Module :: module(), Host :: dispatcher:host()) ->
                 {ok, [inet:ip_address()]}.
%% @private
resolve(Module, Host) ->
    Module:resolve(Host).

would become

%% @private
-spec resolve(Module :: module(), Host :: dispatcher:host()) ->
                 {ok, [inet:ip_address()]}.
resolve(Module, Host) ->
    Module:resolve(Host).

This will be super nice, but I don't know if it's possible at all, without breaking other things.

[elbrujohalcon]

@paulo-ferraz-oliveira can you confirm if this is still happening?
I just tried to format the following module and there was no new line introduced after the comment.

-module(a_module).

-spec resolve(Module :: module(), Host :: dispatcher:host()) -> {ok, [inet:ip_address()]}.
%% @private
resolve(Module, Host) ->
    Module:resolve(Host).

[paulo-ferraz-oliveira]

This seems to have gone away. At least in master.

[elbrujohalcon]

Thanks.