-Wdocumentation should not check the @returns command for Objective-C

function/block pointer properties

The commit r300981 allowed @param/@return commands for function/block
pointer property declarations. This meant that -Wdocumentation started warning
about @return that was used to document properties whose function/block type
returned void. However, prior to that commit, we allowed @return for all
property declarations, because it can be used to document the value that's
returned by the property getter. This commit restores the previous behaviour:
now the @return command can be used to document all properties without warnings.

rdar://24978538

llvm-svn: 301402

clang/lib/AST/CommentSema.cpp

@@ -584,6 +584,10 @@ void Sema::checkReturnsCommand(const BlockCommandComment *Command) {
 
   assert(ThisDeclInfo && "should not call this check on a bare comment");
 
+  // We allow the return command for all @properties because it can be used
+  // to document the value that the property getter returns.
+  if (isObjCPropertyDecl())
+    return;
   if (isFunctionDecl() || isFunctionOrBlockPointerVarLikeDecl()) {
     if (ThisDeclInfo->ReturnType->isVoidType()) {
       unsigned DiagKind;
@@ -610,8 +614,6 @@ void Sema::checkReturnsCommand(const BlockCommandComment *Command) {
     }
     return;
   }
-  else if (isObjCPropertyDecl())
-    return;
 
   Diag(Command->getLocation(),
        diag::warn_doc_returns_not_attached_to_a_function_decl)

clang/test/Sema/warn-documentation.m

@@ -290,4 +290,12 @@ void (^_Nullable blockPointerVariableThatLeadsNowhere)();
  */
 @property int (^blockPointerProperty)(int i);
 
+/**
+ * blockReturnsNothing
+ *
+ * \returns Nothing, but can allow this as this pattern is used to document the
+ * value that the property getter returns.
+ */
+@property void (^blockReturnsNothing)();
+
 @end