Page MenuHomePhabricator

clang-tidy doc: add a note for every checker with an autofix
Needs ReviewPublic

Authored by sylvestre.ledru on Apr 12 2020, 4:21 PM.

Details

Summary

Currently, when looking at a checker documentation, we have to go back
to the whole list or look at the sources to figure out if an autofix
is available or not.

Feel free to propose a better wording

Here is the ugly way I used:
LIST=$(grep Yes list.rst|awk '{print $1}'|cut -d\` -f2)
or f in $LIST; do cat /tmp/a.txt >> $f.rst; done

with /tmp/a.txt containing the text

Diff Detail

Event Timeline

Herald added a project: Restricted Project. · View Herald TranscriptApr 12 2020, 4:21 PM

It'll be reasonable to use two spaces indent. At least this is what mostly used for code blocks. Options are exceptions, but will be good idea to reformat them eventually.

2 spaces instead of 4

alexfh added inline comments.Apr 13 2020, 5:35 AM
clang-tools-extra/docs/clang-tidy/checks/abseil-duration-conversion-cast.rst
29–35 ↗(On Diff #256943)

A few problems with this approach:

  1. Some checkers' docs already have more specific wording about the fix. Adding a generic phase doesn't make the documentation look neat.
  2. The "callable with --fix" part isn't relevant to all clang-tidy frontends. Even for the CLI a reference to the documentation would be more helpful than a mention of this command-line option (there are other relevant options and ways to apply a fix - --fix-errors, -export-fixes + the clang-apply-fixes tool, etc.).

My proposal is to add a mandatory Automatic fixes or Suggested fixes section to all checker documentation files, require the authors to describe the nature of the fix more thoroughly, and use consistent wording when there is no fix. E.g.

Automatic Fixes
^^^^^^^^^^^^^

The check doesn't provide an automatic fix.

or

Automatic Fixes
^^^^^^^^^^^^^

The check provides suggested fixes. See the documentation above for the details.

or

Automatic Fixes
^^^^^^^^^^^^^

The check provides suggested fixes in the following cases:
1.
2.
3.

WDYT?

Makes sense.
I will give it a try :)
thanks

Doing it by hand. @alexfh please let me know if you would be ok with it
(I will do it by hand)

This revision was not accepted when it landed; it landed in state Needs Review.Sun, May 10, 2:39 AM
This revision was automatically updated to reflect the committed changes.
sylvestre.ledru reopened this revision.Sun, May 10, 4:28 AM

has been reverted