clang/test/Sema/warn-documentation.m

   1 // RUN: %clang_cc1 -fsyntax-only -fblocks -Wno-objc-root-class -Wdocumentation -Wdocumentation-pedantic -verify %s
   2 // RUN: %clang_cc1 -xobjective-c++ -fsyntax-only -fblocks -Wno-objc-root-class -Wdocumentation -Wdocumentation-pedantic -verify %s
   3
   4 @class NSString;
   5
   6 // expected-warning@+1 {{empty paragraph passed to '\brief' command}}
   7 /// \brief\author Aaa
   8 @interface Test1
   9 // expected-warning@+2 {{empty paragraph passed to '\brief' command}}
  10 /**
  11  * \brief\author Aaa
  12  * \param aaa Aaa
  13  * \param bbb Bbb
  14  */
  15 + (NSString *)test1:(NSString *)aaa suffix:(NSString *)bbb;
  16
  17 // expected-warning@+2 {{parameter 'aab' not found in the function declaration}} expected-note@+2 {{did you mean 'aaa'?}}
  18 /**
  19  * \param aab Aaa
  20  */
  21 + (NSString *)test2:(NSString *)aaa;
  22
  23 // expected-warning@+1 {{empty paragraph passed to '\brief' command}}
  24 /// \brief\author Aaa
  25 @property int test3; // a property: ObjCPropertyDecl
  26
  27 // expected-warning@+1 {{empty paragraph passed to '\brief' command}}
  28 /// \brief\author Aaa
  29 @property int test4; // a property: ObjCPropertyDecl
  30 @end
  31
  32 // expected-warning@+1 {{empty paragraph passed to '\brief' command}}
  33 /// \brief\author Aaa
  34 @interface Test1()
  35 @end
  36
  37 // expected-warning@+1 {{empty paragraph passed to '\brief' command}}
  38 /// \brief\author Aaa
  39 @implementation Test1 // a class implementation : ObjCImplementationDecl
  40 + (NSString *)test1:(NSString *)aaa suffix:(NSString *)bbb {
  41   return 0;
  42 }
  43
  44 + (NSString *)test2:(NSString *)aaa {
  45   return 0;
  46 }
  47
  48 @synthesize test3; // a property implementation: ObjCPropertyImplDecl
  49 @dynamic test4; // a property implementation: ObjCPropertyImplDecl
  50
  51 // expected-warning@+1 {{empty paragraph passed to '\brief' command}}
  52 /// \brief\author Aaa
  53 NSString *_test5;
  54 @end
  55
  56 // expected-warning@+1 {{empty paragraph passed to '\brief' command}}
  57 /// \brief\author Aaa
  58 @interface Test1(Test1Category) // a category: ObjCCategoryDecl
  59 // expected-warning@+1 {{empty paragraph passed to '\brief' command}}
  60 /// \brief\author Aaa
  61 + (NSString *)test3:(NSString *)aaa;
  62 @end
  63
  64 // expected-warning@+1 {{empty paragraph passed to '\brief' command}}
  65 /// \brief\author Aaa
  66 @implementation Test1(Test1Category) // a category implementation: ObjCCategoryImplDecl
  67 + (NSString *)test3:(NSString *)aaa {
  68   return 0;
  69 }
  70 @end
  71
  72 // expected-warning@+1 {{empty paragraph passed to '\brief' command}}
  73 /// \brief\author Aaa
  74 @protocol TestProto1 // a protocol: ObjCProtocolDecl
  75 @end
  76
  77 int a;
  78
  79 // expected-warning@+1 {{empty paragraph passed to '\brief' command}}
  80 /// \brief\author Aaa
  81 @interface Test4
  82 @end
  83
  84 int b;
  85
  86 @interface TestReturns1
  87 /// \returns Aaa
  88 - (int)test1:(NSString *)aaa;
  89
  90 // expected-warning@+1 {{'\returns' command used in a comment that is attached to a method returning void}}
  91 /// \returns Aaa
  92 - (void)test2:(NSString *)aaa;
  93 @end
  94
  95 // expected-warning@+2 {{parameter 'bbb' not found in the function declaration}} expected-note@+2 {{did you mean 'ccc'?}}
  96 /// \param aaa Meow.
  97 /// \param bbb Bbb.
  98 /// \returns aaa.
  99 typedef int (^test_param1)(int aaa, int ccc);
 100
 101 // expected-warning@+2 {{'@method' command should be used in a comment attached to an Objective-C method declaration}}
 102 @interface I
 103 /*!     @method Base64EncodeEx
 104 */
 105 typedef id ID;
 106 - (unsigned) Base64EncodeEx : (ID)Arg;
 107 @end
 108
 109 // expected-warning@+5 {{'@interface' command should not be used in a comment attached to a non-interface declaration}}
 110 // expected-warning@+5 {{'@classdesign' command should not be used in a comment attached to a non-container declaration}}
 111 // expected-warning@+5 {{'@coclass' command should not be used in a comment attached to a non-container declaration}}
 112 @interface NSObject @end
 113 /*!
 114 @interface IOCommandGate
 115 @classdesign Multiple paragraphs go here.
 116 @coclass myCoClass
 117 */
 118
 119 typedef id OBJ;
 120 @interface IOCommandGate : NSObject {
 121   OBJ iv;
 122 }
 123 @end
 124
 125 // expected-warning@+4 {{'@methodgroup' command should be used in a comment attached to an Objective-C method declaration}}
 126 // expected-warning@+6 {{'@method' command should be used in a comment attached to an Objective-C method declaratio}}
 127 @interface rdar12379114
 128 /*!
 129  @methodgroup Creating a request
 130 */
 131 /*!
 132  @method initWithTimeout is the 2nd method
 133 */
 134 typedef unsigned int NSTimeInterval;
 135 - (id)initWithTimeout:(NSTimeInterval)timeout;
 136 @end
 137
 138 // expected-warning@+2 {{'@protocol' command should not be used in a comment attached to a non-protocol declaration}}
 139 /*!
 140 @protocol PROTO
 141 */
 142 struct S;
 143
 144 /*!
 145   @interface NSArray This is an array
 146 */
 147 @class NSArray;
 148 @interface NSArray @end
 149
 150 // expected-warning@+3 {{unknown command tag name}}
 151 /*!
 152 @interface NSMutableArray
 153 @super NSArray
 154 */
 155 @interface NSMutableArray : NSArray @end
 156
 157 /*!
 158   @protocol MyProto
 159 */
 160 @protocol MyProto @end
 161
 162 // expected-warning@+2 {{'@protocol' command should not be used in a comment attached to a non-protocol declaration}}
 163 /*!
 164  @protocol MyProto
 165 */
 166 @interface INTF <MyProto> @end
 167
 168 // expected-warning@+2 {{'@struct' command should not be used in a comment attached to a non-struct declaration}}
 169 /*!
 170   @struct S1 THIS IS IT
 171 */
 172 @interface S1 @end
 173
 174 // expected-warning@+1 {{unknown command tag name}}
 175 /// \t bbb IS_DOXYGEN_END
 176 int FooBar(void);
 177
 178 /** \brief Module handling the incoming notifications from the system.
 179  *
 180  * This includes:
 181  * - Network Reachability
 182  * - Power State
 183  * - Low Disk
 184  */
 185 @interface BRC : NSObject
 186 - (void)removeReach:(NSObject*)observer;
 187 @end
 188
 189 @implementation BRC : NSObject
 190 - (void)removeReach:(NSObject*)observer // expected-note {{previous declaration is here}}
 191 {
 192 }
 193 - (void)removeReach:(NSObject*)observer // expected-error {{duplicate declaration of method 'removeReach:'}}
 194 {
 195 }
 196 @end
 197
 198 /// @class Asset  <- '@class' may be used in a comment attached to a an interface declaration
 199 @interface Asset : NSObject
 200 @end
 201
 202 // Check that this does not enter an infinite loop
 203 @interface rdar14024851
 204 -(void)meth; // expected-note {{declared here}}
 205 @end
 206
 207 @implementation rdar14024851 // expected-warning {{method definition for 'meth' not found}} expected-note {{previous definition}}
 208 @end
 209
 210 @implementation rdar14024851 // expected-error {{reimplementation}}
 211 /// \brief comment
 212 -(void)meth {}
 213 @end
 214
 215 @interface test_vararg1
 216 /// @param[in] arg something
 217 /// @param[in] ... This is vararg
 218 - (void) VarArgMeth : (id)arg, ...;
 219 @end
 220
 221 @implementation test_vararg1
 222 /// @param[in] arg something
 223 /// @param[in] ... This is vararg
 224 - (void) VarArgMeth : (id)arg, ... {}
 225 @end
 226
 227 /**
 228  * blockPointerVariable
 229  *
 230  * @param i is integer.
 231  * @returns integer.
 232  */
 233 int (^blockPointerVariable)(int i);
 234
 235 struct HasFields {
 236   /**
 237    * blockPointerField
 238    *
 239    * \param i is integer.
 240    * \returns integer.
 241    */
 242   int (^blockPointerFields)(int i);
 243 };
 244
 245 // expected-warning@+5 {{parameter 'p' not found in the function declaration}}
 246 // expected-warning@+5 {{'\returns' command used in a comment that is attached to a function returning void}}
 247 /**
 248  * functionPointerVariable
 249  *
 250  * \param p not here.
 251  * \returns integer.
 252  */
 253 void (^_Nullable blockPointerVariableThatLeadsNowhere)(void);
 254
 255 @interface CheckFunctionBlockPointerVars {
 256   /**
 257    * functionPointerIVar
 258    *
 259    * @param i is integer.
 260    * @returns integer.
 261    */
 262   int (*functionPointerIVar)(int i);
 263
 264   /**
 265    * blockPointerIVar
 266    *
 267    * \param i is integer.
 268    * \returns integer.
 269    */
 270   int (^blockPointerIVar)(int i);
 271 }
 272
 273 /**
 274  * functionPointerProperty
 275  *
 276  * @param i is integer.
 277  * @returns integer.
 278  */
 279 @property int (*functionPointerProperty)(int i);
 280
 281 /**
 282  * blockPointerProperty
 283  *
 284  * \param i is integer.
 285  * \returns integer.
 286  */
 287 @property int (^blockPointerProperty)(int i);
 288
 289 /**
 290  * blockReturnsNothing
 291  *
 292  * \returns Nothing, but can allow this as this pattern is used to document the
 293  * value that the property getter returns.
 294  */
 295 @property void (^blockReturnsNothing)(void);
 296
 297 @end
 298
 299 /*!
 300  * Block typedef with variadic params.
 301  *
 302  * @param a
 303  * works
 304  *
 305  * @param ...
 306  * now should work too.
 307  */
 308 typedef void (^VariadicBlockType)(int a, ...);
 309
 310 // PR42844 - Assertion failures when using typedefed block pointers
 311 typedef void(^VoidBlockType)(void);
 312 typedef VoidBlockType VoidBlockTypeCall(void);
 313 VoidBlockTypeCall *d; ///< \return none
 314 // expected-warning@-1 {{'\return' command used in a comment that is not attached to a function or method declaration}}
 315 VoidBlockTypeCall ^e; ///< \return none
 316 // expected-warning@-1 {{'\return' command used in a comment that is not attached to a function or method declaration}}
 317
 318 #ifdef __cplusplus
 319 @interface HasAnonNamespace @end
 320 @implementation HasAnonNamespace
 321 namespace {}
 322 @end
 323 #endif