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 // rdar://13094352
 102 // expected-warning@+2 {{'@method' command should be used in a comment attached to an Objective-C method declaration}}
 103 @interface I
 104 /*!     @method Base64EncodeEx
 105 */
 106 typedef id ID;
 107 - (unsigned) Base64EncodeEx : (ID)Arg;
 108 @end
 109
 110 // rdar://12379114
 111 // expected-warning@+5 {{'@interface' command should not be used in a comment attached to a non-interface declaration}}
 112 // expected-warning@+5 {{'@classdesign' command should not be used in a comment attached to a non-container declaration}}
 113 // expected-warning@+5 {{'@coclass' command should not be used in a comment attached to a non-container declaration}}
 114 @interface NSObject @end
 115 /*!
 116 @interface IOCommandGate
 117 @classdesign Multiple paragraphs go here.
 118 @coclass myCoClass
 119 */
 120
 121 typedef id OBJ;
 122 @interface IOCommandGate : NSObject {
 123   OBJ iv;
 124 }
 125 @end
 126
 127 // rdar://12379114
 128 // expected-warning@+4 {{'@methodgroup' command should be used in a comment attached to an Objective-C method declaration}}
 129 // expected-warning@+6 {{'@method' command should be used in a comment attached to an Objective-C method declaratio}}
 130 @interface rdar12379114
 131 /*!
 132  @methodgroup Creating a request
 133 */
 134 /*!
 135  @method initWithTimeout is the 2nd method
 136 */
 137 typedef unsigned int NSTimeInterval;
 138 - (id)initWithTimeout:(NSTimeInterval)timeout;
 139 @end
 140
 141 // expected-warning@+2 {{'@protocol' command should not be used in a comment attached to a non-protocol declaration}}
 142 /*!
 143 @protocol PROTO
 144 */
 145 struct S;
 146
 147 /*!
 148   @interface NSArray This is an array
 149 */
 150 @class NSArray;
 151 @interface NSArray @end
 152
 153 // expected-warning@+3 {{unknown command tag name}}
 154 /*!
 155 @interface NSMutableArray
 156 @super NSArray
 157 */
 158 @interface NSMutableArray : NSArray @end
 159
 160 /*!
 161   @protocol MyProto
 162 */
 163 @protocol MyProto @end
 164
 165 // expected-warning@+2 {{'@protocol' command should not be used in a comment attached to a non-protocol declaration}}
 166 /*!
 167  @protocol MyProto
 168 */
 169 @interface INTF <MyProto> @end
 170
 171 // expected-warning@+2 {{'@struct' command should not be used in a comment attached to a non-struct declaration}}
 172 /*!
 173   @struct S1 THIS IS IT
 174 */
 175 @interface S1 @end
 176
 177 // expected-warning@+1 {{unknown command tag name}}
 178 /// \t bbb IS_DOXYGEN_END
 179 int FooBar(void);
 180
 181 // rdar://13836387
 182 /** \brief Module handling the incoming notifications from the system.
 183  *
 184  * This includes:
 185  * - Network Reachability
 186  * - Power State
 187  * - Low Disk
 188  */
 189 @interface BRC : NSObject
 190 - (void)removeReach:(NSObject*)observer;
 191 @end
 192
 193 @implementation BRC : NSObject
 194 - (void)removeReach:(NSObject*)observer // expected-note {{previous declaration is here}}
 195 {
 196 }
 197 - (void)removeReach:(NSObject*)observer // expected-error {{duplicate declaration of method 'removeReach:'}}
 198 {
 199 }
 200 @end
 201
 202 // rdar://13927330
 203 /// @class Asset  <- '@class' may be used in a comment attached to a an interface declaration
 204 @interface Asset : NSObject
 205 @end
 206
 207 // rdar://14024851 Check that this does not enter an infinite loop
 208 @interface rdar14024851
 209 -(void)meth; // expected-note {{declared here}}
 210 @end
 211
 212 @implementation rdar14024851 // expected-warning {{method definition for 'meth' not found}} expected-note {{previous definition}}
 213 @end
 214
 215 @implementation rdar14024851 // expected-error {{reimplementation}}
 216 /// \brief comment
 217 -(void)meth {}
 218 @end
 219
 220 // rdar://14124644
 221 @interface test_vararg1
 222 /// @param[in] arg something
 223 /// @param[in] ... This is vararg
 224 - (void) VarArgMeth : (id)arg, ...;
 225 @end
 226
 227 @implementation test_vararg1
 228 /// @param[in] arg something
 229 /// @param[in] ... This is vararg
 230 - (void) VarArgMeth : (id)arg, ... {}
 231 @end
 232
 233 /**
 234  * blockPointerVariable
 235  *
 236  * @param i is integer.
 237  * @returns integer.
 238  */
 239 int (^blockPointerVariable)(int i);
 240
 241 struct HasFields {
 242   /**
 243    * blockPointerField
 244    *
 245    * \param i is integer.
 246    * \returns integer.
 247    */
 248   int (^blockPointerFields)(int i);
 249 };
 250
 251 // expected-warning@+5 {{parameter 'p' not found in the function declaration}}
 252 // expected-warning@+5 {{'\returns' command used in a comment that is attached to a function returning void}}
 253 /**
 254  * functionPointerVariable
 255  *
 256  * \param p not here.
 257  * \returns integer.
 258  */
 259 void (^_Nullable blockPointerVariableThatLeadsNowhere)(void);
 260
 261 @interface CheckFunctionBlockPointerVars {
 262   /**
 263    * functionPointerIVar
 264    *
 265    * @param i is integer.
 266    * @returns integer.
 267    */
 268   int (*functionPointerIVar)(int i);
 269
 270   /**
 271    * blockPointerIVar
 272    *
 273    * \param i is integer.
 274    * \returns integer.
 275    */
 276   int (^blockPointerIVar)(int i);
 277 }
 278
 279 /**
 280  * functionPointerProperty
 281  *
 282  * @param i is integer.
 283  * @returns integer.
 284  */
 285 @property int (*functionPointerProperty)(int i);
 286
 287 /**
 288  * blockPointerProperty
 289  *
 290  * \param i is integer.
 291  * \returns integer.
 292  */
 293 @property int (^blockPointerProperty)(int i);
 294
 295 /**
 296  * blockReturnsNothing
 297  *
 298  * \returns Nothing, but can allow this as this pattern is used to document the
 299  * value that the property getter returns.
 300  */
 301 @property void (^blockReturnsNothing)(void);
 302
 303 @end
 304
 305 /*!
 306  * Block typedef with variadic params.
 307  *
 308  * @param a
 309  * works
 310  *
 311  * @param ...
 312  * now should work too.
 313  */
 314 typedef void (^VariadicBlockType)(int a, ...);
 315
 316 // PR42844 - Assertion failures when using typedefed block pointers
 317 typedef void(^VoidBlockType)(void);
 318 typedef VoidBlockType VoidBlockTypeCall(void);
 319 VoidBlockTypeCall *d; ///< \return none
 320 // expected-warning@-1 {{'\return' command used in a comment that is not attached to a function or method declaration}}
 321 VoidBlockTypeCall ^e; ///< \return none
 322 // expected-warning@-1 {{'\return' command used in a comment that is not attached to a function or method declaration}}
 323
 324 #ifdef __cplusplus
 325 @interface HasAnonNamespace @end
 326 @implementation HasAnonNamespace
 327 namespace {}
 328 @end
 329 #endif