Comment AST: Add support for variable templates

[aaronpuchert]

Summary

We treat them as variables of course, though if they have function
pointer type we treat them as functions, i.e. allow parameter and return
value specifications. Just like VarDecls.

[gribozavr2]

clang/test/Sema/warn-documentation.cpp

1348

"functionPointerTemplateMember"

clang/include/clang/AST/Comment.h

enum DeclKind {
 
     /// Something that we consider a "class":
     /// \li class/struct,
     /// \li class template,
     /// \li class template (partial) specialization.
     ClassKind,
 
     /// Something that we consider a "variable":
-    /// \li namespace scope variables;
-    /// \li static and non-static class data members;
+    /// \li namespace scope variables and variable templates;
+    /// \li static and non-static class data members and member templates;
     /// \li enumerators.
     VariableKind,
 
     /// A C++ namespace.
     NamespaceKind,
 
     /// A C++ typedef-name (a 'typedef' decl specifier or alias-declaration),
     /// see \c TypedefNameDecl.

clang/lib/AST/Comment.cpp

case Decl::ClassTemplateSpecialization:
     Kind = ClassKind;
     TemplateKind = TemplateSpecialization;
     break;
   case Decl::Record:
   case Decl::CXXRecord:
     Kind = ClassKind;
     break;
   case Decl::Var:
+    if (const VarTemplateDecl *VTD =
+            cast<VarDecl>(CommentDecl)->getDescribedVarTemplate()) {
+      TemplateKind = TemplateSpecialization;
+      TemplateParameters = VTD->getTemplateParameters();
+    }
+    LLVM_FALLTHROUGH;
   case Decl::Field:
   case Decl::EnumConstant:
   case Decl::ObjCIvar:
   case Decl::ObjCAtDefsField:
   case Decl::ObjCProperty:
     if (const auto *VD = dyn_cast<DeclaratorDecl>(CommentDecl))
       TSI = VD->getTypeSourceInfo();
     else if (const auto *PD = dyn_cast<ObjCPropertyDecl>(CommentDecl))
       TSI = PD->getTypeSourceInfo();
     Kind = VariableKind;
     break;
+  case Decl::VarTemplate: {
+    const VarTemplateDecl *VTD = cast<VarTemplateDecl>(CommentDecl);
+    Kind = VariableKind;
+    TemplateKind = Template;
+    TemplateParameters = VTD->getTemplateParameters();
+    if (const VarDecl *VD = VTD->getTemplatedDecl())
+      TSI = VD->getTypeSourceInfo();
+    break;
+  }
   case Decl::Namespace:
     Kind = NamespaceKind;
     break;
   case Decl::TypeAlias:
   case Decl::Typedef:
     Kind = TypedefKind;
     TSI = cast<TypedefNameDecl>(CommentDecl)->getTypeSourceInfo();
     break;

clang/test/Sema/warn-documentation.cpp

 /**
  * functionPointerVariable
  *
  * @param i is integer.
  * @returns integer.
  */
 int (*functionPointerVariable)(int i);
 
+#if __cplusplus >= 201402L
+/**
+ * functionPointerVariableTemplate
+ *
+ * @param i is something.
+ * @returns integer.
+ */
+template<typename T>
+int (*functionPointerVariableTemplate)(T i);
+#endif
+
 struct HasFields {
   /**
    * functionPointerField
    *
    * @param i is integer.
    * @returns integer.
    */
   int (*functionPointerField)(int i);
+
+#if __cplusplus >= 201402L
+  /**
+   * functionPointerTemplateMember
+   *
+   * @tparam T some type.
+   * @param i is integer.
+   * @returns integer.
+   */
+  template<typename T>
+  static int (*functionPointerTemplateMember)(int i);
+#endif
 };
 
 // expected-warning@+5 {{parameter 'p' not found in the function declaration}}
 // expected-warning@+5 {{'\returns' command used in a comment that is attached to a function returning void}}
 /**
  * functionPointerVariable
  *
  * \param p not here.
  * \returns integer.
  */
 void (*functionPointerVariableThatLeadsNowhere)();
 
+#if __cplusplus >= 201402L
+// expected-warning@+8 {{template parameter 'X' not found in the template declaration}}
+// expected-note@+7 {{did you mean 'T'?}}
+// expected-warning@+7 {{parameter 'p' not found in the function declaration}}
+// expected-note@+6 {{did you mean 'x'?}}
+// expected-warning@+6 {{'\returns' command used in a comment that is attached to a function returning void}}
+/**
+ * functionPointerVariable
+ *
+ * \tparam X typo
+ * \param p not here.
+ * \returns integer.
+ */
+template<typename T>
+void (*functionPointerVariableTemplateThatLeadsNowhere)(T x);
+#endif
+
 // Still warn about param/returns commands for variables that don't specify
 // the type directly:
 
 /**
  * FunctionPointerTypedef
  *
  * \param i is integer.
  * \returns integer.