[PR32667] -Wdocumentation should allow @param/@returns for fields/variables

that have a function/block pointer type

This commit improves the -Wdocumentation warning by making sure that @param and
@returns commands won't trigger warnings when used for fields, variables,
or properties whose type is a function/block pointer type. The
function/block pointer type must be specified directly with the declaration,
and when a typedef is used the warning is still emitted.

In the future we might also want to handle the std::function type as well.

rdar://24978538

llvm-svn: 300981

2 files changed, 134 insertions, 0 deletions

diff --git a/clang/test/Sema/warn-documentation.cpp b/clang/test/Sema/warn-documentation.cpp
index 34d8f5fd2da..0c92b2aa029 100644
--- a/clang/test/Sema/warn-documentation.cpp
+++ b/clang/test/Sema/warn-documentation.cpp
@@ -1210,3 +1210,75 @@ template <class T> T test_function (T arg);
 /*!     @function test_function<int>
 */
 template <> int test_function<int> (int arg);
+
+namespace AllowParamAndReturnsOnFunctionPointerVars {
+
+/**
+ * functionPointerVariable
+ *
+ * @param i is integer.
+ * @returns integer.
+ */
+int (*functionPointerVariable)(int i);
+
+struct HasFields {
+  /**
+   * functionPointerField
+   *
+   * @param i is integer.
+   * @returns integer.
+   */
+  int (*functionPointerField)(int i);
+};
+
+// 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)();
+
+// Still warn about param/returns commands for variables that don't specify
+// the type directly:
+
+/**
+ * FunctionPointerTypedef
+ *
+ * \param i is integer.
+ * \returns integer.
+ */
+typedef int (*FunctionPointerTypedef)(int i);
+
+/**
+ * FunctionPointerTypealias
+ *
+ * \param i is integer.
+ * \returns integer.
+ */
+using FunctionPointerTypealias = int (*)(int i);
+
+// expected-warning@+5 {{'@param' command used in a comment that is not attached to a function declaration}}
+// expected-warning@+5 {{'@returns' command used in a comment that is not attached to a function or method declaration}}
+/**
+ * functionPointerVariable
+ *
+ * @param i is integer.
+ * @returns integer.
+ */
+FunctionPointerTypedef functionPointerTypedefVariable;
+
+struct HasMoreFields {
+  // expected-warning@+5 {{'\param' command used in a comment that is not attached to a function declaration}}
+  // expected-warning@+5 {{'\returns' command used in a comment that is not attached to a function or method declaration}}
+  /**
+   * functionPointerTypealiasField
+   *
+   * \param i is integer.
+   * \returns integer.
+   */
+  FunctionPointerTypealias functionPointerTypealiasField;
+};
+
+}
diff --git a/clang/test/Sema/warn-documentation.m b/clang/test/Sema/warn-documentation.m
index 5e95e2a1e8a..a8538f02be1 100644
--- a/clang/test/Sema/warn-documentation.m
+++ b/clang/test/Sema/warn-documentation.m
@@ -229,3 +229,65 @@ int FooBar();
 - (void) VarArgMeth : (id)arg, ... {}
 @end
 
+/**
+ * blockPointerVariable
+ *
+ * @param i is integer.
+ * @returns integer.
+ */
+int (^blockPointerVariable)(int i);
+
+struct HasFields {
+  /**
+   * blockPointerField
+   *
+   * \param i is integer.
+   * \returns integer.
+   */
+  int (^blockPointerFields)(int i);
+};
+
+// 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 (^blockPointerVariableThatLeadsNowhere)();
+
+@interface CheckFunctionBlockPointerVars {
+  /**
+   * functionPointerIVar
+   *
+   * @param i is integer.
+   * @returns integer.
+   */
+  int (*functionPointerIVar)(int i);
+
+  /**
+   * blockPointerIVar
+   *
+   * \param i is integer.
+   * \returns integer.
+   */
+  int (^blockPointerIVar)(int i);
+}
+
+/**
+ * functionPointerProperty
+ *
+ * @param i is integer.
+ * @returns integer.
+ */
+@property int (*functionPointerProperty)(int i);
+
+/**
+ * blockPointerProperty
+ *
+ * \param i is integer.
+ * \returns integer.
+ */
+@property int (^blockPointerProperty)(int i);
+
+@end