This commit adds a chapter about clang-tidy integrations

[MarinaKalashina]

Summary

Proposing changes to clang-tools-extra/docs/clang-tidy/index.rst

'Using clang-tidy' was split into 2 chapters:

• 'Standalone tool' (the previous content of 'Using clang-tidy')
• 'Clang-tidy integrated' (a new chapter)

[JonasToth]

I like the overview, maybe a link to clangd here might help, as there is currently a lot of effort of integrating clang-tidy into it. (@sammccall WDYT?)

docs/clang-tidy/index.rst

23

I think a blank line here would not hurt.

274

Could you please align the elements in the columns, some are off by one.

[alexfh]

Should this chapter be a separate page linked from index.md?

[sammccall]

In D54945#1309467, @JonasToth wrote:

I like the overview, maybe a link to clangd here might help, as there is currently a lot of effort of integrating clang-tidy into it. (@sammccall WDYT?)

This would be great! The integration is not yet complete, so I'm not sure if it's best to add now or later.

For the table:

• on-the-fly inspection: yes (I think - this means showing fixes overlaid on the code as you edit, right?)
• check list configuration (GUI): no
• options to checks (GUI): no
• configuration via .clang-tidy file: this will be the supported mechanism. Not done yet.
• custom clang-tidy binary: no

The behavior today is that three hard-coded checks are always enabled, as a proof-of-concept. Configuration via .clang-tidy is the main missing piece.
Clang-tidy diagnostics are shown along with others, as-you-type. Fixes can be applied.
Static analyzer checks will probably never be supported.

[Eugene.Zelenko]

docs/clang-tidy/index.rst

304

Please limit line width to 80 characters. Same in other places.

327

Will be good idea to mention native plugin, clang-tidy-vs.

[MarinaKalashina]

Fixes:

• empty line before 'Standalone tool'
• table columns with '+/-' aligned
• line width limited to 80 (except for the table)

Additions:

• clang-tidy-vs plugin
• Clangd in the intro, the table, and CLion's paragraph

[alexfh]

In D54945#1316251, @MarinaKalashina wrote:

Fixes:

• empty line before 'Standalone tool'
• table columns with '+/-' aligned
• line width limited to 80 (except for the table)

Additions:

• clang-tidy-vs plugin
• Clangd in the intro, the table, and CLion's paragraph

Did you forget to add a new file to the patch?

Please also include full context into the diff. See https://llvm.org/docs/Phabricator.html

[MarinaKalashina]

In D54945#1318278, @alexfh wrote:

In D54945#1316251, @MarinaKalashina wrote:

Fixes:

• empty line before 'Standalone tool'
• table columns with '+/-' aligned
• line width limited to 80 (except for the table)

Additions:

• clang-tidy-vs plugin
• Clangd in the intro, the table, and CLion's paragraph

Did you forget to add a new file to the patch?

Please also include full context into the diff. See https://llvm.org/docs/Phabricator.html

Sorry but the new diff was included to the patch.. I can see the updates as Diff 176328. Could you please check and let me know if it does not work? Thank you.

[alexfh]

In D54945#1318283, @MarinaKalashina wrote:

In D54945#1318278, @alexfh wrote:

In D54945#1316251, @MarinaKalashina wrote:

Fixes:

• empty line before 'Standalone tool'
• table columns with '+/-' aligned
• line width limited to 80 (except for the table)

Additions:

• clang-tidy-vs plugin
• Clangd in the intro, the table, and CLion's paragraph

Did you forget to add a new file to the patch?

Please also include full context into the diff. See https://llvm.org/docs/Phabricator.html

Sorry but the new diff was included to the patch.. I can see the updates as Diff 176328. Could you please check and let me know if it does not work? Thank you.

Please see the screenshot. The diff might be reversed (new vs. old) or just wrong. And there's no context (not overly important in this particular patch, but still makes it more convenient to review).

[MarinaKalashina]

Full-context patch for the changes introduced in the previous commit.

[MarinaKalashina]

@alexfh Thanks a lot for your patience and help. I've made another revision, now with the diff made by 'git show HEAD -U999999' to have the full context availlable.

[alexfh]

In D54945#1318343, @MarinaKalashina wrote:

@alexfh Thanks a lot for your patience and help. I've made another revision, now with the diff made by 'git show HEAD -U999999' to have the full context availlable.

I don't know how this happened, but the diff is still almost empty. This is what I get when I click on the "Download raw diff":

Index: docs/clang-tidy/index.rst
===================================================================
--- docs/clang-tidy/index.rst
+++ docs/clang-tidy/index.rst
@@ -403,7 +403,7 @@
 
     // Silent only the specified diagnostics for the next line
     // NOLINTNEXTLINE(google-explicit-constructor, google-runtime-int)
-    Foo(bool param);
+    Foo(bool param); 
   };
 
 The formal syntax of ``NOLINT``/``NOLINTNEXTLINE`` is the following:

It's definitely not a common problem, since there are other patches in review, which are displayed just fine.

[alexfh]

In D54945#1321301, @alexfh wrote:

In D54945#1318343, @MarinaKalashina wrote:

@alexfh Thanks a lot for your patience and help. I've made another revision, now with the diff made by 'git show HEAD -U999999' to have the full context availlable.

I don't know how this happened, but the diff is still almost empty.

A correction: it's now empty (and it was broken in a different way last time).

Could you verify that you're correctly following one of the processed described in the documentation (https://llvm.org/docs/Phabricator.html)? It looks like you're uploading only one commit from the whole branch.

[ilya-biryukov]

Maybe try to use Arcanist for uploading diffs?
The web interface can be confusing at times, Arcanist is more reliable (LLVM docs have pointers to the Arcanist documentation to get started)

[MarinaKalashina]

Another attempt to update the patch with the following fixes:

• empty line before 'Standalone tool'
• table columns with '+/-' aligned
• line width limited to 80 (except for the table)
• clang-tidy-vs plugin added
• Clangd added to the intro, the table, and the CLion's paragraph

[ilya-biryukov]

Thanks for the update! We still need to solve the technicality here: could you please upload the diff with full context? See LLVM docs for an example on how this can be done with various version controls (the -U99999 args are important, they are the ones that produce diffs with enough lines around it)

[MarinaKalashina]

Full-context patch

[MarinaKalashina]

@ilya-biryukov Thank you for a quick response and sorry for so many iterations. I uploaded a full-context version; hopefully this time it's alright - on my side, it finally looks like a proper full-context diff.

[Eugene.Zelenko]

Please run script from D55523 over your changes.

[alexfh]

docs/clang-tidy/index.rst

262

So how about moving this chapter to a separate page and adding a link to it at the top of this document? While certainly useful, the information in this section has a different focus from the rest of the documentation. Given that the document has grown significantly, I suggest to split out this section and the "Getting involved" section. (The latter can be done separately)

[MarinaKalashina]

@alexfh Just for me to be sure, should there be the following structure in http://clang.llvm.org/extra/index.html:
Clang-Tidy

The list of clang-tidy checks
Using clang-tidy
Suppressing Undesired Diagnostics
Clang-tidy Integrated (separate page)
Getting Involved (separate page)

And should the latter two pages be linked from 'Clang-Tidy' index.rs like 'The list of clang-tidy checks', which is placed in 'See also'?
Thank you.

docs/clang-tidy/index.rst

262

Just for me to be sure, should there be the following structure in http://clang.llvm.org/extra/index.html:
Clang-Tidy

The list of clang-tidy checks
Using clang-tidy
Suppressing Undesired Diagnostics
Clang-tidy Integrated (separate page)
Getting Involved (separate page)

And should the latter two pages be linked from 'Clang-Tidy' index.rs like 'The list of clang-tidy checks', which is placed in 'See also'?
Thank you.

[alexfh]

In D54945#1340528, @MarinaKalashina wrote:

@alexfh Just for me to be sure, should there be the following structure in http://clang.llvm.org/extra/index.html: ...

Roughly like that. More specifically, I'd suggest to modify the See also section of clang-tidy/index.rst as follows:

See also:

.. toctree::
   :maxdepth: 1

   The list of clang-tidy checks <checks/list>
   Clang-tidy IDE/Editor Integrations <integrations>
   Getting Involved <contribution>

The order of TOC items in http://clang.llvm.org/extra/index.html will be slightly weird (the three external docs will be placed before the headings of the main document), but that doesn't seem like a huge problem (and may be fixable).

[MarinaKalashina]

Extracting 'Getting Involved' and 'Clang-tidy integrations' to separate pages linked in See Also.

[MarinaKalashina]

@alexfh Thank you, please see the updated structure.
@Eugene.Zelenko Done, the only warnings I got were about the table rows width.

[Eugene.Zelenko]

docs/clang-tidy/integrations.rst

118 ↗

(On Diff #181018)

Please add newline.

[MarinaKalashina]

integrations.rst - end of file new line

[MarinaKalashina]

restoring full content

[alexfh]

Awesome! Thanks a lot ! LG

[Eugene.Zelenko]

I would suggest to rename contribution to Contributing (see LLVM documentation) and integrations to Integrations.

Will be also good idea to fix D55523 script warnings.

[MarinaKalashina]

files renamed: contribution.rst to Contributing.rst, integrations.rst to Integrations.rst

[MarinaKalashina]

@Eugene.Zelenko

I would suggest to rename contribution to Contributing (see LLVM documentation) and integrations to Integrations.

Sure, done.

Will be also good idea to fix D55523 script warnings.

The script warns about double spaces and line width in the table, for example:

warning: line 39 contains double spaces
warning: line 39 is in excess of 80 characters (196)

These spaces and width are intended since they 'draw' the table layout. Do you think we could ignore such warnings in this particular case?

[Eugene.Zelenko]

In D54945#1355920, @MarinaKalashina wrote:

@Eugene.Zelenko

I would suggest to rename contribution to Contributing (see LLVM documentation) and integrations to Integrations.

Sure, done.

Will be also good idea to fix D55523 script warnings.

The script warns about double spaces and line width in the table, for example:

warning: line 39 contains double spaces
warning: line 39 is in excess of 80 characters (196)

These spaces and width are intended since they 'draw' the table layout. Do you think we could ignore such warnings in this particular case?

Sure, it's fine to leave table as it is. Same thing is done in LLDB code where tables are excluded from Clang-format.

[MarinaKalashina]

@Eugene.Zelenko @alexfh Thank you! How should I proceed with the revision now? Do I get it right from https://llvm.org/docs/Phabricator.html#committing-a-change, that without commit access, I need to ask for committing the changes for me?

[Eugene.Zelenko]

clang-tools-sphinx-docs bot is failing because of:

Warning, treated as error:
/home/buildbot/llvm-build-dir/clang-tools-sphinx-docs/llvm/src/tools/clang/tools/extra/docs/clang-tidy/Contributing.rst:61: ERROR: Unknown target name: "how to setup tooling for llvm".

Frankly I don't know what is proper way to handle cross-module documentation links.

[Eugene.Zelenko]

I fixed links.

[Eugene.Zelenko]

By the word, I noticed that HTTP was used and replaced it with HTTPS in Contributing.rst. Will be good idea to do the same in other documentation.

[Eugene.Zelenko]

I requested merge of updated documentation into 8.0 branch in PR40369.

docs/clang-tidy/index.rst

 
 Using clang-tidy
 ================
+Standalone tool
+---------------
 
 :program:`clang-tidy` is a `LibTooling`_-based tool, and it's easier to work
 with if you set up a compile command database for your project (for an example

           value:           'some value'
       ...
 
+
+Clang-tidy integrated
+---------------------
+Apart from being a standalone tool, :program:`clang-tidy` is integrated into various IDEs,
+code analyzers, and editors. The following table shows the most well-known :program:`clang-tidy` integrations
+in detail.
+
++--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+
+|                                      |        Feature                                                                                                                                           |
++======================================+========================+=================================+==========================+=========================================+==========================+
+|  **Tool**                            | On-the-fly inspection  | Check list configuration (GUI)  | Options to checks (GUI)  | Configuration via ``.clang-tidy`` files | Custom clang-tidy binary |
++--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+
+|A.L.E. for Vim                        |         \+\            |               \-\               |           \-\            |                 \-\                     |           \+\            |
++--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+
+|Clang Power Tools for Visual Studio   |          \-\           |                \+\              |           \-\            |                 \+\                     |            \-\           |
++--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+
+|CLion IDE                             |         \+\            |                \+\              |           \+\            |                 \+\                     |           \+\            |
++--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+
+|CodeChecker                           |          \-\           |               \-\               |           \-\            |                 \-\                     |           \+\            |
++--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+
+|CPPCheck                              |          \-\           |               \-\               |           \-\            |                 \-\                     |           \-\            |
++--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+
+|CPPDepend                             |          \-\           |               \-\               |           \-\            |                 \-\                     |           \-\            |
++--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+
+|Flycheck for Emacs                    |          \+\           |               \-\               |           \-\            |                 \+\                     |           \+\            |
++--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+
+|KDevelop IDE                          |          \-\           |               \+\               |           \+\            |                 \+\                     |           \+\            |
++--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+
+|Qt Creator IDE                        |          \+\           |               \+\               |           \-\            |                 \-\                     |           \+\            |
++--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+
+|ReSharper C++ for Visual Studio       |          \+\           |               \+\               |           \-\            |                 \+\                     |           \-\            |
++--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+
+|Syntastic for Vim                     |          \+\           |               \-\               |           \-\            |                 \-\                     |           \+\            |
++--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+
+|Visual Assist for Visual Studio       |          \+\           |               \+\               |           \-\            |                 \-\                     |           \-\            |
++--------------------------------------+------------------------+---------------------------------+--------------------------+-----------------------------------------+--------------------------+
+
+
+**IDEs**
+
+.. _CLion: https://www.jetbrains.com/clion/
+.. _integrates clang-tidy: https://www.jetbrains.com/help/clion/clang-tidy-checks-support.html
+
+CLion_ 2017.2 and later `integrates clang-tidy`_ as an extension to the built-in code analyzer.
+Inspections and applicable quick-fixes are performed on the fly, and checks can be configured in the standard command line
+format. In this integration, you can switch to the :program:`clang-tidy` binary different from the bundled one and pass
+configuration via ``.clang-tidy`` files instead of using the IDE settings. Starting from version 2018.1, CLion allows
+configuring options for particular checks.
+
+.. _KDevelop: https://www.kdevelop.org/
+.. _kdev-clang-tidy: https://github.com/KDE/kdev-clang-tidy/
+
+KDevelop_ with the kdev-clang-tidy_ plugin, starting from version 5.1, performs static analysis using :program:`clang-tidy`. The plugin launches the :program:`clang-tidy` binary
+from the specified location and parses its output to provide a list of issues.
+
+.. _QtCreator: https://www.qt.io/
+.. _Clang Code Model: http://doc.qt.io/qtcreator/creator-clang-codemodel.html
+
+QtCreator_ 4.6 integrates :program:`clang-tidy` warnings into the editor diagnostics under the `Clang Code Model`_.
+To employ :program:`clang-tidy` inspection in QtCreator, you need to create a copy of one of the presets and choose
+the checks to be performed in the Clang Code Model Warnings menu.
+
+.. _MS Visual Studio: https://visualstudio.microsoft.com/
+.. _ReSharper C++: https://www.jetbrains.com/help/resharper/Clang_Tidy_Integration.html
+.. _Visual Assist: https://docs.wholetomato.com/default.asp?W761
+.. _Clang Power Tools: https://marketplace.visualstudio.com/items?itemName=caphyon.ClangPowerTools
+
+`MS Visual Studio`_ can integrate :program:`clang-tidy` by means of three different tools.
+The `ReSharper C++`_ extension, version 2017.3 and later, provides seamless :program:`clang-tidy` integration:
+checks and quick-fixes run alongside native inspections.
+Apart from that, ReSharper C++ incorporates :program:`clang-tidy` as a separate step of its code clean-up process.
+`Visual Assist`_ build 2210 also includes a subset of :program:`clang-tidy` checklist to inspect the code as you edit.
+Another way to bring :program:`clang-tidy` functionality to Visual Studio is the `Clang Power Tools`_ plugin,
+which includes most of the :program:`clang-tidy` checks and runs them during compilation or as a separate step of code analysis.
+
+**Editors**
+
+.. _Flycheck: https://github.com/ch1bo/flycheck-clang-tidy
+.. _Syntastic: https://github.com/vim-syntastic/syntastic
+.. _A.L.E.: https://github.com/w0rp/ale
+.. _Emacs24: https://www.gnu.org/s/emacs/
+.. _Vim: https://www.vim.org/
+
+Emacs24_, when expanded with the Flycheck_ plugin, incorporates the :program:`clang-tidy` inspection into the syntax analyzer.
+For Vim_, you can use Syntastic_, which includes :program:`clang-tidy`, or `A.L.E.`_,
+a lint engine that applies :program:`clang-tidy` along with other linters.
+
+**Analyzers**
+
+.. _CPPDepend: https://www.cppdepend.com/cppdependv2018
+.. _CPPCheck: https://sourceforge.net/p/cppcheck/news/
+.. _CodeChecker: https://github.com/Ericsson/codechecker
+.. _plugin: https://github.com/Ericsson/CodeCheckerEclipsePlugin
+
+:program:`clang-tidy` is integrated in CPPDepend_ starting from version 2018.1 and CPPCheck_ 1.82. CPPCheck integration lets
+you import Visual Studio solutions and run the :program:`clang-tidy` inspection on them.
+The CodeChecker_ application of version 5.3 or later, which also comes as a plugin_ for Eclipse,
+supports :program:`clang-tidy` as a static analysis instrument and allows to use a custom :program:`clang-tidy` binary.
+
 Suppressing Undesired Diagnostics
 =================================