1 #include <petscsys.h>
2
3 typedef int testType;
4
5 /*@C
6 testWellFormedFunctionDocString - Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
7 incididunt ut labore et dolore magna aliqua.
8
9 Not Collective, Synchronous
10
11 Input Parameters:
12 + viewer - a PetscViewer
13 - x - an int
14
15 Output Parameter:
16 + viewer2 - a PetscViewer
17 - y - a pointer
18
19 Level: beginner
20
21 Notes:
22 Lorem ipsum dolor sit amet, for example\:
23
24 References:
25 Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
26
27 .seealso: `testIllFormedFunctionDocString()`, `testType`
28 @*/
testWellFormedFunctionDocString(PetscViewer viewer,PetscInt x,PetscViewer viewer2,PetscScalar * y)29 PetscErrorCode testWellFormedFunctionDocString(PetscViewer viewer, PetscInt x, PetscViewer viewer2, PetscScalar *y)
30 {
31 return 0;
32 }
33
34 /*@C Lorem ipsum dolor sit amet
35 someOtherFunctionName - Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
36 eiusmod tempor incididunt ut labore et dolore magna aliqua. Excepteur sint occaecat cupidatat
37 non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Sed ut
38 perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium,
39 totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae
40 vitae dicta sunt explicabo.
41
42 Not Collective, Synchronous
43
44 Input Parameters:
45 + viewer - a PetscViewer
46
47 Output Parameter:
48 - y - a pointer
49 + cnd - a boolean
50 . z - a nonexistent parameter
51
52 level: Lorem ipsum dolor sit amet
53
54 Level:
55 Beginner
56
57 Developer Notes:
58 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut
59 labore et dolore magna aliqua. Excepteur sint occaecat cupidatat non proident, sunt in culpa
60 qui officia deserunt mollit anim id est laborum as follows:
61
62 Notes Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
63 incididunt ut labore et dolore magna aliqua. Excepteur sint occaecat cupidatat non proident,
64 sunt in culpa qui officia deserunt mollit anim id est laborum example.
65
66 Fortran Notes:
67 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut
68 labore et dolore magna aliqua. Excepteur sint occaecat cupidatat non proident, sunt in culpa
69 qui officia deserunt mollit anim id est laborum instance:
70
71 References: Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
72
73 .seealso: testNonExistentFunction(), testNonExistentType,
74 testIllFormedFunctionDocString(), `testNonExistentFunction()`, testIllFormedMinimalDocString()
75 @*/
76
testIllFormedFunctionDocString(PetscViewer viewer,PetscInt x,PetscScalar * y,PetscBool cond)77 PetscErrorCode testIllFormedFunctionDocString(PetscViewer viewer, PetscInt x, PetscScalar *y, PetscBool cond)
78 {
79 return 0;
80 }
81
82 /*
83 Not Collective, Synchronous
84
85 input parms:
86 . foo
87
88 Output params:
89 + bar -
90
91 References:
92 Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
93 .seealso: testNonExistentFunction(), testNonExistentType,`testNonExistentFunction()
94 */
testIllFormedMinimalDocString(void)95 PetscErrorCode testIllFormedMinimalDocString(void)
96 {
97 return 0;
98 }
99
100 /*@C
101 testTerbleSpelingDocstring - Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
102 eiusmod tempor incididunt ut labore et dolore magna aliqua.
103
104 input prametirs:
105 + viewer - a PetsViewer
106 - x - a PetscInt
107
108 output Psrammmetrs:
109 . y - a PetscScalar pointer
110
111 optnS dtaaSE:
112 - -option_a - foo
113 - -option_b [filename][:[~]<foo,bar,baz>[:[~]bop]] - descr
114 lvl: itnmediate
115
116 .zeeakso:
117 @*/
testTerribleSpellingDocString(PetscViewer viewer,PetscInt x,PetscScalar * y)118 PetscErrorCode testTerribleSpellingDocString(PetscViewer viewer, PetscInt x, PetscScalar *y)
119 {
120 return 0;
121 }
122
123 /*@ asdadsadasdas
124 testCustomFortranInterfaceDocString - Lorem ipsum dolor sit amet, consectetur adipiscing elit
125
126 Input Parameters:
127 + string - a char pointer
128 - function_ptr - a function pointer
129
130 Level:
131
132 .seealso: Lorem(), `ipsum()`, dolor(), `sit(), `amet()`, consectetur(), adipiscing(), elit()`
133 @*/
testCustomFortranInterfaceDocString(char ******* string,PetscErrorCode (* function_ptr)(PetscInt))134 PetscErrorCode testCustomFortranInterfaceDocString(char *******string, PetscErrorCode (*function_ptr)(PetscInt))
135 {
136 return 0;
137 }
138
139 /* a random comment above a function */
function()140 void function() { }
141
142 PETSC_INTERN PetscErrorCode testInternFunction();
143
144 /*@
145 testInternFunction - an internal function
146
147 Level: developer
148
149 .seealso: function()
150 @*/
testInternFunction()151 PetscErrorCode testInternFunction()
152 {
153 return 0;
154 }
155
156 /*@
157 testStaticFunction - an internal function
158
159 Level: developer
160
161 .seealso: function()
162 @*/
testStaticFunction()163 static PetscErrorCode testStaticFunction()
164 {
165 return 0;
166 }
167
168 /*@
169 testAllParamsUndocumented - lorem
170
171 Level: beginner developer
172
173 Example Usage:
174 .vb
175 int a;
176 double multiline;
177 char codeBlock;
178 .ve
179
180 .seealso:
181 @*/
testAllParamsUndocumented(PetscInt a,PetscInt b)182 PetscErrorCode testAllParamsUndocumented(PetscInt a, PetscInt b)
183 {
184 return testStaticFunction();
185 }
186
187 /*@
188 testParameterGrouping ipsum
189
190 Input parameters:
191 - a,b - some params
192 + nonExistentParam - this param does not exist
193 . ... - variadic arguments
194
195 Level dev
196
197 .see also: testStaticFunction()
198 @*/
testParameterGrouping(PetscInt a,PetscInt b,...)199 PetscErrorCode testParameterGrouping(PetscInt a, PetscInt b, ...)
200 {
201 return 0;
202 }
203
204 /*@
205 testScatteredVerbatimBlocks - bla
206
207 Input Parameters:
208 + alpha - an alpha
209 .vb
210 int a_code_block;
211 .ve
212 - beta - a beta
213
214 Level: beginner
215
216 .seealso: `Foo()`
217 @*/
testScatteredVerbatimBlocks(PetscInt alpha,PetscInt beta)218 PetscErrorCode testScatteredVerbatimBlocks(PetscInt alpha, PetscInt beta)
219 {
220 return 0;
221 }
222
223 /*@
224 testBadParamListDescrSep - foo
225
226 Input Parameters:
227 + alpha, an alpha
228 - beta = a beta
229
230 Level: beginner
231
232 .seealso: Foo()
233 @*/
testBadParamListDescrSep(PetscInt alpha,PetscInt beta)234 PetscErrorCode testBadParamListDescrSep(PetscInt alpha, PetscInt beta)
235 {
236 return 0;
237 }
238
239 /*@
240 testBadMidSentenceColons - Lorem:
241
242 Notes:
243 Lorem ipsum dolor sit amet:, consectetur adipiscing elit: sed do: eiusmod tempor: incididunt ut
244 labore et dolore: magna aliqua: Excepteur: sint occaecat cupidatat non proident, sunt: in culpa
245 qui officia: deserunt mollit: anim id est: laborum as follows:
246
247 Level: beginner
248
249 .seealso: `Foo()
250 @*/
testBadMidSentenceColons(void)251 PetscErrorCode testBadMidSentenceColons(void)
252 {
253 return 0;
254 }
255
256 /*MC
257 MYTYPE - MYTYPE = "mytype"
258
259 Level: developer
260
261 .seealso: MATAIJ
262 M*/
263
testFloatingDocstring(void)264 PetscErrorCode testFloatingDocstring(void)
265 {
266 return 0;
267 }
268
269 /*@M
270 testExplicitSynopsis - Lorem Ipsum
271
272 Synopsis:
273 #include "testheader.h"
274 PetscErrorCode testExplicitSynopsis(PetscInt foo, PetscReal bar, void *baz)
275
276 Collective
277
278 Input Parameters:
279 + foo - a foo
280 - bar - a bar
281
282 Output Parameter:
283 . baz - a baz
284
285 Level: beginner
286
287 .seealso: `testExplicitSynopsisBad()`
288 M@*/
testExplicitSynopsis_Private(PetscScalar unknown,PetscInt foo,PetscReal bar,void * baz)289 PetscErrorCode testExplicitSynopsis_Private(PetscScalar unknown, PetscInt foo, PetscReal bar, void *baz)
290 {
291 return 0;
292 }
293
294 /* testBadDocString - asdadsasd
295 */
testBadDocString(PetscInt n)296 PetscErrorCode testBadDocString(PetscInt n)
297 {
298 return 0;
299 }
300
301 /*C testBadDocStringMissingChar - asdadsasd
302
303 Input Parameter:
304 . n - the n
305
306 Level: beginner
307
308 .seealso: `testBadDocString()`
309 */
testBadDocStringMissingChar(PetscInt n)310 PetscErrorCode testBadDocStringMissingChar(PetscInt n)
311 {
312 return 0;
313 }
314
315 /*C@
316 testBadDocStringCharOutOfOrder - asdadsasd
317
318 Input Parameter:
319 . n - the n
320
321 Level: beginner
322
323 .seealso: `testBadDocString()`
324 */
testBadDocStringCharOutOfOrder(PetscInt n)325 PetscErrorCode testBadDocStringCharOutOfOrder(PetscInt n)
326 {
327 return 0;
328 }
329
330 /*
331 testInternalLinkageDocstring = This looks like a docstring, acts like a docstring, but it is
332 not a docstring, no diagnostics should be emitted for this function
333
334 Input parm:
335 * hello - asdasd
336
337 Notes:
338 This is because the function has internal linkage, and hence it is developer documentation!
339
340 level: dev
341
342 .seealso testWellFormedFunctionDocString()
343 */
testInternalLinkageDocstring(PetscInt param)344 static PetscErrorCode testInternalLinkageDocstring(PetscInt param)
345 {
346 return 0;
347 }
348
349 /*@
350 testSingleFunctionArgNotFound - asdasdasdasd
351
352 Input parm:
353 + unrelated - A function arg
354
355 lvel: dev
356
357 .seealso: `testBadDocString()
358
359 @*/
testSingleFunctionArgNotFound(PetscScalar some_function_arg)360 PetscErrorCode testSingleFunctionArgNotFound(PetscScalar some_function_arg)
361 {
362 return 0;
363 }
364
365 extern PetscErrorCode testPredeclarationCursorIgnored(int, int *);
366
367 /*
368 testPredeclarationCursorIgnored - the cursor above this will be ignored!
369
370 Inp Paramet:
371 . asdasd - an arg
372
373 Ouput Pameter:
374 . another_arg_asd22 - another arg
375
376 Level: beg
377
378 .seealso: testPredeclarationCursorIgnored()`, foo()`, `Bar, baz()
379 */
380
testPredeclarationCursorIgnored(int arg,int * another_arg)381 PetscErrorCode testPredeclarationCursorIgnored(int arg, int *another_arg)
382 {
383 return 0;
384 }
385
386 /*@
387 testFunctionPointerArguments - the first set of arguments are unnamed and should be errored
388
389 Input Parameters:
390 + foo - a foo
391 . bar - a bar
392 - baz - a baz
393
394 Calling sequence of `foo`:
395 + foo_parm1 - an int
396 . foo_parm2 - a double
397 - foo_parm3 - a float
398
399 Calling sequence of `bar`:
400 + bar_parm1 - an int
401 . bar_parm2 - a double
402 - bar_parm3 - a float
403
404 Calling sequence of `baz`:
405 + bop - a bop
406 . blitz - a blitz
407 . baz_parm1 - an int
408 . baz_parm2 - a double
409 - baz_parm3 - a float
410
411 Level: developer
412
413 Notes:
414 But bars arguments should correctly match! Additionally, this function requires a 'C'
415 interface marker!
416
417 .seealso: `testPredeclarationCursorIgnored()`
418 */
testFunctionPointerArguments(int (* foo)(int,double,float),int (* bar)(int bar_parm1,double bar_parm2,float bar_parm3),void (* baz)(int (* bop)(void),void (* blitz)(void (*)(void)),int baz_parm1,double baz_parm2,float baz_parm3))419 PetscErrorCode testFunctionPointerArguments(int (*foo)(int, double, float), int (*bar)(int bar_parm1, double bar_parm2, float bar_parm3), void (*baz)(int (*bop)(void), void (*blitz)(void (*)(void)), int baz_parm1, double baz_parm2, float baz_parm3))
420 {
421 return 0;
422 }
423
424 /*@
425 testDeprecated - check that deprecated (since VERSION) works
426
427 Level: deprecated (since 3.17)
428
429 .seealso: `testIllFormedDeprecated()`
430 */
testDeprecated(void)431 PetscErrorCode testDeprecated(void)
432 {
433 return PETSC_SUCCESS;
434 }
435
436 /*@
437 testIllFormedDeprecated - check that deprecated (since VERSION) works
438
439 Input Parameters:
440 + foo - a nonexistent foo
441 . bar - a nonexistent bar
442 - baz - a nonexistent baz
443
444 Level: dpcrtd (since 3.18.5)
445
446 .seealso: [](ch_matrices), `testDeprecated()`, [Matrix Factorization](sec_matfactor)
447 */
testIllFormedDeprecated(void)448 PetscErrorCode testIllFormedDeprecated(void)
449 {
450 return PETSC_SUCCESS;
451 }
452
453 /*@
454 testValidInOutParams - check that in-out params work
455
456 Input Parameter:
457 . foo - the input description for an in-out param
458
459 Output Parameter:
460 . foo - the output description for an in-out param
461
462 Level: beginner
463
464 .seealso: `testWellFormedFunctionDocString()`
465 */
testValidInOutParams(int * foo)466 PetscErrorCode testValidInOutParams(int *foo)
467 {
468 return PETSC_SUCCESS;
469 }
470
471 /*@
472 testInvalidInOutParams - check that in-out params work
473
474 Input Parameter:
475 + foo - the input description for an in-out param
476 + baz - asdasdasd
477 - foo - a duplicate description
478
479 Output Parameters:
480 . bop = asdas
481 - foo - the output description for an in-out param
482 - foo - a duplicate description2
483
484 Level: beginner
485
486 .seealso: `testWellFormedFunctionDocString()`
487 */
testInvalidInOutParams(int * foo)488 PetscErrorCode testInvalidInOutParams(int *foo)
489 {
490 return PETSC_SUCCESS;
491 }
492
493 /*@C
494 testFunctionParmsSameName - Sets the residual evaluation routine for least-square applications
495
496 Logically Collective
497
498 Input Parameters:
499 + tao - the `Tao` context
500 . res - the res
501 . func - the residual evaluation routine
502 - ctx - [optional] user-defined context for private data for the function evaluation
503 routine (may be `NULL`)
504
505 Calling sequence of `func`:
506 + tao - the optimizer
507 . x - input vector
508 . f - function value vector
509 - ctx - [optional] user-defined function context
510
511 Level: beginner
512
513 .seealso: [](ch_tao), `Tao`, `TaoSetObjective()`, `TaoSetJacobianRoutine()`
514 @*/
testFunctionParmsSameName(int tao,double res,PetscErrorCode (* func)(int tao,double x,double f,PetscCtx ctx),PetscCtx ctx)515 PetscErrorCode testFunctionParmsSameName(int tao, double res, PetscErrorCode (*func)(int tao, double x, double f, PetscCtx ctx), PetscCtx ctx)
516 {
517 return PETSC_SUCCESS;
518 }
519
520 /*@C
521 testFunctionParmsSameNameInOut - Sets the residual evaluation routine for least-square applications
522
523 Logically Collective
524
525 Input Parameters:
526 + tao - the `Tao` context (and in-out parm)
527 . res - the res
528 . func - the residual evaluation routine
529 - ctx - [optional] user-defined context for private data for the function evaluation
530 routine (may be `NULL`)
531
532 Calling sequence of `func`:
533 + tao - the optimizer
534 . x - input vector
535 . f - function value vector
536 - ctx - [optional] user-defined function context
537
538 Output Parameter:
539 . tao - the in-output parm
540
541 Level: beginner
542
543 .seealso: [](ch_tao), `Tao`, `TaoSetObjective()`, `TaoSetJacobianRoutine()`
544 @*/
testFunctionParmsSameNameInOut(int * tao,double res,PetscErrorCode (* func)(int tao,double x,double f,PetscCtx ctx),PetscCtx ctx)545 PetscErrorCode testFunctionParmsSameNameInOut(int *tao, double res, PetscErrorCode (*func)(int tao, double x, double f, PetscCtx ctx), PetscCtx ctx)
546 {
547 return PETSC_SUCCESS;
548 }
549
550 // PetscClangLinter pragma disable: -fdoc.*
551 /*@C Lorem ipsum dolor sit amet
552 someOtherFunctionName - Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
553 eiusmod tempor incididunt ut labore et dolore magna aliqua. Excepteur sint occaecat cupidatat
554 non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Sed ut
555 perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium,
556 totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae
557 vitae dicta sunt explicabo.
558
559 Not Collective, Synchronous
560
561 Input Parameters:
562 + viewer - a PetscViewer
563
564 Output Parameter:
565 - y - a pointer
566 + cnd - a boolean
567 . z - a nonexistent parameter
568
569 level: Lorem ipsum dolor sit amet
570
571 Level:
572 Beginner
573
574 Developer Notes:
575 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut
576 labore et dolore magna aliqua. Excepteur sint occaecat cupidatat non proident, sunt in culpa
577 qui officia deserunt mollit anim id est laborum as follows:
578
579 Notes Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
580 incididunt ut labore et dolore magna aliqua. Excepteur sint occaecat cupidatat non proident,
581 sunt in culpa qui officia deserunt mollit anim id est laborum example.
582
583 Fortran Notes:
584 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut
585 labore et dolore magna aliqua. Excepteur sint occaecat cupidatat non proident, sunt in culpa
586 qui officia deserunt mollit anim id est laborum instance:
587
588 References: Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
589
590 .seealso: testNonExistentFunction(), testNonExistentType,
591 testIllFormedFunctionDocString(), `testNonExistentFunction()`, testIllFormedMinimalDocString()
592 @*/
593
testBadDocStringIgnoreAll()594 PetscErrorCode testBadDocStringIgnoreAll()
595 {
596 return PETSC_SUCCESS;
597 }
598
599 // A dummy comment
600 /* another dummy comment */
601 /*@C
602 testIgnoringSpuriousComments - Insert point coordinates (defined over the reference cell)
603 within each cell
604
605 Level: beginner
606
607 Notes:
608 This verbatim section contains nested comments, but that's OK!
609 .vb
610 // a nested comment
611 .ve
612
613 .seealso: `testBadDocString()`
614 @*/
testIgnoringSpuriousComments()615 PetscErrorCode testIgnoringSpuriousComments()
616 {
617 return PETSC_SUCCESS;
618 }
619
620 /*@C
621 testCheckingSectionIndentationAfterSwitch - the second section heading should be properly
622 re-indented
623
624 Input Parameter:
625 . foo - a foo
626
627 OutputParameter:
628 + bar - a bar for
629 example this is not a heading
630
631 Level: intermediate
632
633 .seealso: `testBadDocString()`
634 @*/
testCheckingSectionIndentationAfterSwitch(int foo,double * bar)635 PetscErrorCode testCheckingSectionIndentationAfterSwitch(int foo, double *bar)
636 {
637 return PETSC_SUCCESS;
638 }
639
640 /*@C
641 testReferencesFalsePositive - this should not pick up a references section
642
643 Level: beginner
644
645 Notes:
646 A per- MPI communicator garbage dictionary is created to store
647 references to objects destroyed using `PetscObjectDelayedDestroy()`.
648
649 .seealso: `testBadDocString()`
650 @*/
testReferencesFalsePositive()651 PetscErrorCode testReferencesFalsePositive()
652 {
653 return PETSC_SUCCESS;
654 }
655
656 /*@C
657 testOptionsDatabaseFalsePositive - this should not pick up an
658 options database section
659
660 Level: beginner
661
662 Notes:
663 A per- MPI communicator garbage dictionary is created to store an
664 options database to objects destroyed using `PetscObjectDelayedDestroy()`.
665
666 .seealso: `testBadDocString()`
667 @*/
testOptionsDatabaseFalsePositive()668 PetscErrorCode testOptionsDatabaseFalsePositive()
669 {
670 return PETSC_SUCCESS;
671 }
672
673 /*@C
674 testLeftFlushSeeAlsoFalsePositive - this should only indent the seealso once
675
676 Level: beginner
677
678 .seealso:`thisShouldOnlyBeShiftedOverByOneSpace()`,
679 `andThisShouldBeLeftAlone()`
680 @*/
testLeftFlushSeeAlsoFalsePositive()681 PetscErrorCode testLeftFlushSeeAlsoFalsePositive()
682 {
683 return PETSC_SUCCESS;
684 }
685
686 /*@C
687 testNoteFalsePositive - this is note a notes heading, note
688 that there
689
690 Level: beginner
691
692 .seealso: `Foo`
693 @*/
testNoteFalsePositive()694 PetscErrorCode testNoteFalsePositive()
695 {
696 return PETSC_SUCCESS;
697 }
698