[clang-format] update --files help description

[ychen]

Summary

correlates the option with reponse file concept.

[MyDeveloperDay]

clang/docs/ClangFormat.rst

29

if response files are so common place why not say it here

clang-format [options] [@file]

I personally don't believe we need to document how a shell works

72–73

if you google "response files" you don't get anything that leads to understand what they are. I understand what it means but I'm not convinced others who have not come across it before will. I don't personally think this change adds anything.

[probinson]

The option handling in clang-format itself would need to be updated as well.

clang/docs/ClangFormat.rst

29

Pretty sure it's not the shell doing the expansion here? Certainly Clang has explicit code for deciding between gnu-style and windows-style handling.

[MyDeveloperDay]

Its Is a minor point, but when using --files, the shell will allow me to autocomplete..

 clang-format -verbose -n -files ./cla<TAB>
 clang-format -verbose -n -files ./clang/d<TAB>
 etc...

all the way to the file
 clang-format -verbose -n -files ./clang/docs/tools/clang-formatted-files.txt

with @ I have to be pixel perfect in my path.. so I'm more likely to go wrong

clang-format -verbose -n @./cla<TAB> does nothing.

that feels like a positive for the --files.

[probinson]

clang/docs/ClangFormat.rst

72–74

I was thinking something like this. In particular, call the argument a "filename" and then say what it should look like. The old description with a "string" argument reads like it might want to be
--files=file1,file2,file3
or something like that.

[ychen]

• address comments

[probinson]

The help text in ClangFormat.cpp for the --files option needs to be updated the same way.
Note using cl::value_desc("filename") is what you need to change the meta-variable in the help output.

[ychen]

• make corresponding change in the commandline

[HazardyKnusperkeks]

It's too long ago for me. Does the --files option take multiple file names on the command line, or a file containing the file names? If the latter the patch generally looks good.

Except for the @<file> part. (Which also isn't handles by clang-format, or is it?)

[probinson]

In D135115#3839547, @HazardyKnusperkeks wrote:

It's too long ago for me. Does the --files option take multiple file names on the command line, or a file containing the file names? If the latter the patch generally looks good.

It wants the filename of a text file containing a list of filenames, one per line.

[ychen]

In D135115#3839547, @HazardyKnusperkeks wrote:

Except for the @<file> part. (Which also isn't handles by clang-format, or is it?)

It is not. It is handled by the LLVM commandline library. https://llvm.org/docs/CommandLine.html#response-files

[owenpan]

clang/docs/ClangFormat.rst

29

We should not modify the file directly. See below.

72–73

It should be edited in ClangFormat.cpp as this file is generated by dump_format_help.py.

[rymiel]

NOTE: Clang-Format Team Automated Review Comment

It looks like your clang-format review does not contain any unit tests, please try to ensure all code changes have a unit test (unless this is an NFC or refactoring, adding documentation etc..)

Add your unit tests in clang/unittests/Format and you can build with ninja FormatTests. We recommend using the verifyFormat(xxx) format of unit tests rather than EXPECT_EQ as this will ensure you change is tolerant to random whitespace changes (see FormatTest.cpp as an example)

For situations where your change is altering the TokenAnnotator.cpp which can happen if you are trying to improve the annotation phase to ensure we are correctly identifying the type of a token, please add a token annotator test in TokenAnnotatorTest.cpp

[owenpan]

clang/docs/ClangFormat.rst

72–73

Fixed in c47c480b1845.

clang/docs/ClangFormat.rst

.. code-block:: console
   OVERVIEW: A tool to format C/C++/Java/JavaScript/JSON/Objective-C/Protobuf/C# code.
 
   If no arguments are specified, it formats the code from standard input
   and writes the result to the standard output.
   If <file>s are given, it reformats the files. If -i is specified
   together with <file>s, the files are edited in-place. Otherwise, the
   result is written to the standard output.
 
-  USAGE: clang-format [options] [<file> ...]
+  USAGE: clang-format [options] [@<file>] [<file> ...]
 
   OPTIONS:
 
   Clang-format options:
 
     --Werror                       - If set, changes formatting warnings to errors
     --Wno-error=<value>            - If set don't error out on the specified warning type.
       =unknown                     -   If set, unknown format options are only warned about.
Clang-format options:
     --fallback-style=<string>      - The name of the predefined style used as a
                                      fallback in case clang-format is invoked with
                                      -style=file, but can not find the .clang-format
                                      file to use. Defaults to 'LLVM'.
                                      Use -fallback-style=none to skip formatting.
     --ferror-limit=<uint>          - Set the maximum number of clang-format errors to emit
                                      before stopping (0 = no limit).
                                      Used only with --dry-run or -n
-    --files=<string>               - Provide a list of files to run clang-format
+    --files=<filename>             - A file containing a list of files to process, one
+                                     per line.
     -i                             - Inplace edit <file>s, if specified.
     --length=<uint>                - Format a range of this length (in bytes).
                                      Multiple ranges can be formatted by specifying
                                      several -offset and -length pairs.
                                      When only a single -offset is specified without
                                      -length, clang-format will format up to the end
                                      of the file.
                                      Can only be used with one input file.
     --lines=<string>               - <start line>:<end line> - format a range of

clang/tools/clang-format/ClangFormat.cpp

SortIncludes("sort-includes",
                  cl::cat(ClangFormatCategory));
 
 static cl::opt<std::string> QualifierAlignment(
     "qualifier-alignment",
     cl::desc("If set, overrides the qualifier alignment style\n"
              "determined by the QualifierAlignment style flag"),
     cl::init(""), cl::cat(ClangFormatCategory));
 
-static cl::opt<std::string>
-    Files("files", cl::desc("Provide a list of files to run clang-format"),
-          cl::init(""), cl::cat(ClangFormatCategory));
+static cl::opt<std::string> Files(
+    "files",
+    cl::desc("A file containing a list of files to process, one per line."),
+    cl::value_desc("filename"),
 
 static cl::opt<bool>
     Verbose("verbose", cl::desc("If set, shows the list of processed files"),
             cl::cat(ClangFormatCategory));
 
 // Use --dry-run to match other LLVM tools when you mean do it but don't
 // actually do it
 static cl::opt<bool>