@format collides with edoc

[elbrujohalcon]

As detected by @awalterschulze on WhatsApp/erlfmt#277, we probably need a new tag format.

[awalterschulze]

Apparently it is just a warning, but still could be worth cleaning up.

[elbrujohalcon]

Indeed. It looks like this…

/path/to/file.erl, function my_fun/0: at line 3: warning: tag @format not recognized.

…or…

/path/to/file.erl,  in module header: at line 3: warning: tag @format not recognized.

…even if you write it like this:

%%% @doc This module description.
%%%      More docs.
%%% @end
%%% @format ignore.

[elbrujohalcon]

But that means that we can't just use another word. We need a different way to tag stuff… and we risk edoc picking that up and adding it to the documentation. Not good.

[awalterschulze]

That is a very good point, hmmm.

[awalterschulze]

I was thinking something like #format , but then as you say we risk edoc putting this into the generated documentation.

[elbrujohalcon]

We could use user-defined macros, i.e. {@format …} but that would require users who want to skip the warning to add this to their rebar.config files:

{edoc_opts, [{def, [{format, ""}]}]}.

Not sure if a plugin can auto-add that thing so the user doesn't need to do it manually.

[awalterschulze]

Aha okay, but if they do not add it, they still just get a warning right?

[elbrujohalcon]

Right!

[awalterschulze]

Then this sounds very promising.

[awalterschulze]

I have not checked this, but apparently edoc does allow comments inside edoc, such that the following won't be picked up by edoc as documentation, since it is a comment inside a comment.

% % @format

Notice the space between the two percentages.

[paulo-ferraz-oliveira]

Haha, so hackish. I love it. I wonder if documenting it as such, though, will be more of a headache than not. (even with a "Caveats" section, developers don't often read doc.s).

[awalterschulze]

Yeah it is true and probably the main concern, but whatever we pick this would be the new default for --insert-pragma and --require-pragma would check for both.

[awalterschulze]

I will do a bit of checking of these options on Wednesday, I hope.

[awalterschulze]

If I add the comment

%% {@format}

and run

$ rebar3 shell --start-clean
> edoc:files(["/Users/walterschulze/code/src/github.com/WhatsApp/erlfmt/src/erlfmt.erl"]).

Then I don't get a warning and I haven't even added any edoc_opts to my rebar.config
Are you sure the {edoc_opts, [{def, [{format, ""}]}]}. is needed?

[awalterschulze]

Ah I see, I only get the warning if it is after a %% @doc comment.

[elbrujohalcon]

For context, I tried with rebar3 edoc not within a shell.

[awalterschulze]

Ah nice, yes even with rebar3 edoc I only get the warning for

%% @doc
%% {@format}
%% @end

And the warning goes away if I add

{edoc_opts, [{def, [{format, ""}]}]}.

to the rebar.config

If however I write only

%% {@format}

without any @doc before it and without a rebar.config addition, then I do not get a warning.

If I write

%% {@format}
%% @doc
%% bla
%% @end

without any @doc before it and without a rebar.config addition, then I also do not get a warning.

[elbrujohalcon]

What if you use @format (i.e. without the curly braces) in that same context, then?

[awalterschulze]

All configurations with %% @format with curly braces give a warning

in module header: at line 2: warning: tag @format not recognized.

[awalterschulze]

So looks like both options:

%% {@format}

and

% % @format

would not create any warnings from edoc or extra text in generated by edoc

[awalterschulze]

From a require_pragma standpoint is easy to support all variants.
It is only a question of which one would be recommended and inserted with insert pragma

[elbrujohalcon]

Yeah… on this project we don't care about pragmas… and we already have support for -format as an attribute.
I think for us the easiest one will be % % @format and it will be more than enough.

[awalterschulze]

I am going to take a stab at implement the single space and see how it goes.

[awalterschulze]

Actually forgot that @format does not have to be in the first comment, so it actually does matter, since {@format} can be after @doc, so %% % @format is the better choice.

[awalterschulze]

WhatsApp/erlfmt#281

[awalterschulze]

Decided on %%% % @format for a default of mimicking the number of percentages if @format follows some other comments, for example

%% bla
%% %@format

This was after we did a new analyses, to find that triple percentage is actually quite popular, before the module pragma
https://github.com/WhatsApp/erlfmt/blob/master/doc/FormattingDecisionComments/module_comments.md