[clang-tidy] Add more descriptive comments and examples in misc-definitions-in-headers check.

[alexfh]

docs/clang-tidy/checks/misc-definitions-in-headers.rst

8 ↗

(On Diff #57908)

It wouldn't be a large problem, if linker was always able to detect ODR violations. However, there are cases, where it can't do so. You can still append "in case these headers are included from multiple translation units." to the previous sentence.

35 ↗

(On Diff #57908)

s/multiply defined/defined multiple times/

47 ↗

(On Diff #57908)

s/a inline/an inline/

53 ↗

(On Diff #57908)

s/funtion/function/

60 ↗

(On Diff #57908)

full specialization of a function template ...

[hokein]

Address review comments.

[hokein]

fix a nit.

[alexfh]

LG. Thank you!

clang-tools-extra/trunk/docs/clang-tidy/checks/misc-definitions-in-headers.rst

 .. title:: clang-tidy - misc-definitions-in-headers
 
 misc-definitions-in-headers
 ===========================
 
 Finds non-extern non-inline function and variable definitions in header files,
-which can lead to potential ODR violations.
+which can lead to potential ODR violations in case these headers are included
+from multiple translation units.
 
 .. code:: c++
 
    // Foo.h
-   int a = 1; // Warning.
+   int a = 1; // Warning: variable definition.
    extern int d; // OK: extern variable.
 
    namespace N {
-     int e = 2; // Warning.
+     int e = 2; // Warning: variable definition.
    }
 
-   // Internal linkage variable definitions are ignored for now.
+   // Warning: variable definition.
+   const char* str = "foo";
+
+   // OK: internal linkage variable definitions are ignored for now.
    // Although these might also cause ODR violations, we can be less certain and
    // should try to keep the false-positive rate down.
    static int b = 1;
    const int c = 1;
+   const char* const str2 = "foo";
 
-   // Warning.
+   // Warning: function definition.
    int g() {
      return 1;
    }
 
-   // OK: inline function definition.
+   // OK: inline function definition is allowed to be defined multiple times.
    inline int e() {
      return 1;
    }
 
    class A {
     public:
-     int f1() { return 1; } // OK: inline member function definition.
+     int f1() { return 1; } // OK: implicitly inline member function definition is allowed.
      int f2();
+     static int d;
+   };
+
+   // Warning: not an inline member function definition.
+   int A::f2() { return 1; }
+
+   // OK: class static data member declaration is allowed.
+   int A::d = 1;
+
+   // OK: function template is allowed.
+   template<typename T>
+   T f3() {
+     T a = 1;
+     return a;
+   }
+
+   // Warning: full specialization of a function template is not allowed.
+   template <>
+   int f3() {
+     int a = 1;
+     return a;
+   }
+
+   template <typename T>
+   struct B {
+     void f1();
    };
 
-   int A::f2() { return 1; } // Warning.
+   // OK: member function definition of a class template is allowed.
+   template <typename T>
+   void B<T>::f1() {}