Noissue - clang-format configuration file for C++

c++/clang-format/README.md

 clang-format-eyeo
 =================
 
-A file containing style configuration for [`clang-format`](http://clang.llvm.org/docs/ClangFormat.html)

[Vasily Kuznetsov, 2017/09/11 10:44:33]

We are generally trying to keep the lines under 80 characters in README files in
this repo. It would be nice to reformat this README as well unless you think it
would hurt readability. In cases of long links, one possible option is to
convert them to footnote-like links like this:

    Lorem ipsum [dolor][1] sit amet...
    ...anim id est laborum.

    [1]: https://en.wiktionary.org/wiki/dolor

[Eric, 2017/09/15 13:09:01]

Fixed in patch set 3.
Number-footnotes are kind of awful for maintenance unless
automatically-generated. I did discover, however, that numeric identifiers are
not necessary; text identifiers are also permitted. I used that syntax.

-that formats according to the [Adblock Plus coding style guide](https://adblockplus.org/coding-style#cpp)
-for C++.
+A file containing style configuration for [`clang-format`][clang-format-docs]
+that formats according to the
+[Adblock Plus coding style guide][abp-coding-style-cpp] for C++.
 
 Installation
 ------------
 
 When `clang-format` receives its style configuration from a file, it searches
 for style configuration in the directory of each input file and then each parent
 directory. Copy the format file to the parent directory of the working
 directory. In this way it will `clang-format` will find the format file and
 the version control system will not.
 
-The configuration file must be named either "`.clang-format`" or "`_clang-format`".
-At the present time there's no command line option to specify the file name.
+The configuration file must be named either "`.clang-format`" or
+"`_clang-format`". At the present time there's no command line option to specify
+the file name.
 
 Usage  
 -----
 
     clang-format -style=file [...]
     
 The option "-style=file" (note that this is the word "file", not a file name)
 says to perform a directory search for the configuration. For the rest of the 
 command line, see the `clang-format` documentation link above.
+
+Notes
+-----
+
+`clang-format` is a complete reformatter; it largely ignores whitespace within
+the input and reformats code according to its specified rules. Its treatment of
+whitespace within comments, however, is different, within which it preserves
+whitespace by default. If the automatically-formatted code is not acceptable,
+interventions are available.
+
+* Formatting can be turned on and off with explicit special comments. 
+
+```
+    // clang-format off
+    // clang-format on
+    /* clang-format off */
+    /* clang-format on */
+```
+          
+* Line-end comments contain an embedded newline that `clang-format` will retain.
+To prevent a manually-split line from unwrapping, add a `//`-comment at the end
+of the line; it can be empty.
+
+For more information, see the answer to this Stack Overflow question:
+[Clang-format line breaks][SO-1]
+
+Clang Version Support
+---------------------
+The present version is for Clang 4. One option (`BreakConstructorInitializers`)
+we're using has changed in Clang 5. If you want to use Clang 5, edit the file as
+part of installation. Uncomment the new version and comment out the old one.
+
+
+[clang-format-docs]: http://clang.llvm.org/docs/ClangFormat.html
+[abp-coding-style-cpp]: https://adblockplus.org/coding-style#cpp
+[SO-1]: https://stackoverflow.com/questions/33656800/clang-format-line-breaks#answer-34362422