@format collides with edoc
Opened this issue · 26 comments
As detected by @awalterschulze on WhatsApp/erlfmt#277, we probably need a new tag format.
Apparently it is just a warning, but still could be worth cleaning up.
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.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.
That is a very good point, hmmm.
I was thinking something like #format , but then as you say we risk edoc putting this into the generated documentation.
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.
Aha okay, but if they do not add it, they still just get a warning right?
Right!
Then this sounds very promising.
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.
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).
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.
I will do a bit of checking of these options on Wednesday, I hope.
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?
Ah I see, I only get the warning if it is after a %% @doc comment.
For context, I tried with rebar3 edoc not within a shell.
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.
What if you use @format (i.e. without the curly braces) in that same context, then?
All configurations with %% @format with curly braces give a warning
in module header: at line 2: warning: tag @format not recognized.
So looks like both options:
%% {@format}
and
% % @format
would not create any warnings from edoc or extra text in generated by edoc
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
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.
I am going to take a stab at implement the single space and see how it goes.
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.
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