Update documentation

docs/source/information/develop/clang-tools.rst

@@ -5,10 +5,10 @@ Clang Tools
 is a tool that implements automatic source code formatting.
 It can be used to automatically enforce the layout rules for Sming.
 
-`clang-tidy <https://releases.llvm.org/8.0.1/tools/clang/tools/extra/docs/clang-tidy/index.html>`__
-is a C++ “linter” tool to assist with diagnosing and fixing  typical programming errors
-such as style violations, interface misuse, or bugs that can be deduced via static analysis.
-It is provided as part of 
+`clang-tidy <https://clang.llvm.org/extra/clang-tidy/>`__
+is a C++ “linter” tool to assist with diagnosing and fixing typical programming errors
+including portability/readability issues, bug-prone code constructs,
+interface misuse, or bugs that can be deduced via static analysis.
 
 You can find details for the current release at https://releases.llvm.org/download.html.
 Note that *clang-format* is part of the main **Clang** project, whilst *clang-tidy* can be
@@ -31,15 +31,15 @@ systems.
    Different versions of clang-format can produce different results,
    despite using the same configuration file.
 
-   We are using version 8.0.1 of clang-format and clang-tidy on our
+   We are using version 8.0.1 of clang-format on our
    Continuous Integration (CI) System.
-   
+
    You should install the same version on your development computer.
 
 
 
-Configuration
--------------
+clang-format
+------------
 
 Rules
 ~~~~~
@@ -60,7 +60,7 @@ in the `ClangFormat documentation <https://clang.llvm.org/docs/ClangFormat.html>
 Eclipse IDE
 ^^^^^^^^^^^
 
-For our Eclipse IDE, which is our preferred IDE, we recommend installing
+For the Eclipse IDE we recommend installing
 the `CppStyle plugin <https://github.com/wangzw/CppStyle>`__. You can
 configure your IDE to auto-format the code on “Save” using the
 recommended coding style and/or format according to our coding style
@@ -79,10 +79,10 @@ Single File
 
    If you want to directly apply the coding standards from the command line
    you can run the following command::
-   
+
       cd $SMING_HOME
       clang-format -style=file -i Core/<modified-file>
-   
+
    Where ``Core/<modified-file>`` should be replaced with the path to
    the file that you have modified.
 
@@ -91,10 +91,10 @@ All files
    The following command will run again the coding standards formatter over
    all C, C++ and header files inside the ``Sming/Core``, ``samples`` and 
    other key directories::
-   
+
       cd $SMING_HOME
       make cs
-   
+
    The command needs time to finish. So be patient. It will go over all
    files and will try to fix any coding style issues.
 
@@ -105,7 +105,7 @@ All files
       make cs
    
    from your project directory.
-   
+
 Eclipse
 ~~~~~~~
 
@@ -116,3 +116,64 @@ Alternatively, you can manually apply the coding style rules by selecting the so
 C, C++ or header file or a selection in it and run the ``Format`` command
 (usually Ctrl-Shift-F).
 
+
+clang-tidy
+----------
+
+Configuration
+~~~~~~~~~~~~~
+
+No specific version is required but generally you should aim to use the most recent version
+available in your distribution. Version 17.0.6 was used at time of writing these notes.
+
+The default tool configuration is defined in the
+`.clang-tidy <https://github.com/SmingHub/Sming/blob/develop/.clang-tidy>`__
+file, located in the root directory of the framework.
+
+.. note::
+
+   Unlike clang-format, clang-tidy has to be able to compile the target code in order to perform static analysis.
+   Code must build without errors for **Host** architecture.
+
+   Clang has more limited `constexpr` support than GCC so cannot parse some of the FlashString
+   and NanoTime code without modification.
+   However, these changes are only made when `__clang__` is defined and do not affect regular builds with GCC.
+
+   No object code is generated by clang-tidy.
+
+Usage
+-----
+
+Only source files which haven't been built are inspected.
+So, to restrict which code gets processed built the entire application normally,
+then 'clean' the relevant modules before proceeding with clang-tidy.
+
+For example:
+
+```
+cd $SMING_HOME/../samples/Basic_Servo
+make -j SMING_SOC=host
+make clean Servo-clean
+make CLANG_TIDY=clang-tidy
+```
+
+If you want to fix a particular type of problem, it's usually easiest to be explicit::
+
+   make CLANG_TIDY="clang-tidy --checks='-*,modernize-use-equals-default' --fix"
+
+Remember to run ``make cs`` and check the output before committing!
+
+If you want to provide a custom configuration file::
+
+   make CLANG_TIDY="clang-tidy --config-file=myTidyConfig"
+
+
+.. note::
+
+   clang-tidy can take a long time to do its work, so it's tempting to use the `-j` option
+   to speed things up.
+   You may see some corrupted output though as the output from multiple clang-tidy
+   instances aren't serialised correctly.
+   It's usually fine to get a rough 'first-pass' indication of any problems though.
+
+   However, if attempting to apply fixes **DO NOT** use the -j option as this will result in corrupted output.