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 C@*/ 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 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 */ 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 C@*/ 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 @*/ 134 PetscErrorCode testCustomFortranInterfaceDocString(char *******string, PetscErrorCode (*function_ptr)(PetscInt)) 135 { 136 return 0; 137 } 138 139 /* a random comment above a 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 @*/ 151 PetscErrorCode testInternFunction() 152 { 153 return 0; 154 } 155 156 /*@ 157 testStaticFunction - an internal function 158 159 Level: developer 160 161 .seealso: function() 162 @*/ 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 @*/ 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 @*/ 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 @*/ 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 @*/ 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 @*/ 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 MC*/ 263 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@*/ 289 PetscErrorCode testExplicitSynopsis_Private(PetscScalar unknown, PetscInt foo, PetscReal bar, void *baz) 290 { 291 return 0; 292 } 293 294 /* testBadDocString - asdadsasd 295 */ 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 */ 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 */ 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 */ 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 @*/ 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 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 */ 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 */ 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 */ 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 */ 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 */ 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 @*/ 515 PetscErrorCode testFunctionParmsSameName(int tao, double res, PetscErrorCode (*func)(int tao, double x, double f, void *ctx), void *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 @*/ 545 PetscErrorCode testFunctionParmsSameNameInOut(int *tao, double res, PetscErrorCode (*func)(int tao, double x, double f, void *ctx), void *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 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 @*/ 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 @*/ 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 @*/ 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 @*/ 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 @*/ 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 @*/ 694 PetscErrorCode testNoteFalsePositive() 695 { 696 return PETSC_SUCCESS; 697 } 698