Clang Project

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