1<--- FIXED ---> 2-------------------------------------------------------------------------------------------- 3ERROR 0: ./src/sys/tests/linter/testValidFunctionDocStrings.c:77:16 4'testIllFormedFunctionDocString' of type 'PetscErrorCode (PetscViewer, PetscInt, PetscScalar *, PetscBool)' (a.k.a. 'int (_p_PetscViewer *, int, double *, PetscBool)') 5 75: @*/ 6 76: 7> 77: PetscErrorCode testIllFormedFunctionDocString(PetscViewer viewer, PetscInt x, PetscScalar *y, PetscBool cond) 8 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 9 78: { 10 79: return 0; 11 12Invalid comment begin line, must only contain '/*' and sowing identifier [-fdoc-sowing-chars]: 13 32: } 14 33: 15> 34: /*@C Lorem ipsum dolor sit amet 16 ^^^^^^^^^^^^^^^^^^^^^^^^^^ 17 35: someOtherFunctionName - Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do 18 36: eiusmod tempor incididunt ut labore et dolore magna aliqua. Excepteur sint occaecat cupidatat 19 20Invalid line-spacing between docstring and the symbol it describes. The docstring must appear immediately above its target [-fdoc-symbol-spacing]: 21 74: testIllFormedFunctionDocString(), `testNonExistentFunction()`, testIllFormedMinimalDocString() 22 75: @*/ 23> 76: 24 77: PetscErrorCode testIllFormedFunctionDocString(PetscViewer viewer, PetscInt x, PetscScalar *y, PetscBool cond) 25 78: { 26 27Invalid indentation (3), all regular (non-empty, non-parameter, non-seealso) text must be indented to 2 columns [-fdoc-indentation]: 28 42: Not Collective, Synchronous 29 43: 30> 44: Input Parameters: 31 ^^^ 32 45: + viewer - a PetscViewer 33 46: 34 35Solitary parameter list entry must start with '.' [-fdoc-param-list-prefix]: 36 43: 37 44: Input Parameters: 38> 45: + viewer - a PetscViewer 39 ^ 40 46: 41 47: Output Parameter: 42 43First multi parameter list entry must start with '+' [-fdoc-param-list-prefix]: 44 46: 45 47: Output Parameter: 46> 48: - y - a pointer 47 ^ 48 49: + cnd - a boolean 49 50: . z - a nonexistent parameter 50 51Multi parameter list entry must start with '.' [-fdoc-param-list-prefix]: 52 47: Output Parameter: 53 48: - y - a pointer 54> 49: + cnd - a boolean 55 ^ 56 50: . z - a nonexistent parameter 57 51: 58 59Last multi parameter list entry must start with '-' [-fdoc-param-list-prefix]: 60 48: - y - a pointer 61 49: + cnd - a boolean 62> 50: . z - a nonexistent parameter 63 ^ 64 51: 65 52: level: Lorem ipsum dolor sit amet 66 67Description 'a pointer' must be aligned to 1 space from longest (valid) argument 'y' [-fdoc-param-list-alignment]: 68 46: 69 47: Output Parameter: 70> 48: - y - a pointer 71 ^^^^^^^^^^^^^^^^^^^^ 72 49: + cnd - a boolean 73 50: . z - a nonexistent parameter 74 75Extra docstring parameter 'z' not found in symbol parameter list [-fdoc-param-list-func-parameter-documentation]: 76 48: - y - a pointer 77 49: + cnd - a boolean 78> 50: . z - a nonexistent parameter 79 ^ 80 51: 81 52: level: Lorem ipsum dolor sit amet 82 83maybe you meant 'x' of type 'PetscInt' (a.k.a. 'int') 84 75: @*/ 85 76: 86> 77: PetscErrorCode testIllFormedFunctionDocString(PetscViewer viewer, PetscInt x, PetscScalar *y, PetscBool cond) 87 ^^^^^^^^^^ 88 78: { 89 79: return 0; 90 91 92Invalid header spelling. Expected 'Level' found 'level' [-fdoc-section-header-spelling]: 93 50: . z - a nonexistent parameter 94 51: 95> 52: level: Lorem ipsum dolor sit amet 96 ^^^^^ 97 53: 98 54: Level: 99 100Level subheading must be lowercase, expected 'beginner' found 'Beginner' [-fdoc-inline-list-level-casefold]: 101 53: 102 54: Level: 103> 55: Beginner 104 ^^^^^^^^ 105 56: 106 57: Developer Notes: 107 108seealso values must be (1) space away from colon not (50) [-fdoc-inline-list-formatting]: 109 71: References: Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. 110 72: 111> 73: .seealso: testNonExistentFunction(), testNonExistentType, 112 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 113 74: testIllFormedFunctionDocString(), `testNonExistentFunction()`, testIllFormedMinimalDocString() 114 75: @*/ 115 116Found self-referential seealso entry 'testIllFormedFunctionDocString()'; your documentation may be good but it's not *that* good [-fdoc-inline-list-seealso-self-reference]: 117 72: 118 73: .seealso: testNonExistentFunction(), testNonExistentType, 119> 74: testIllFormedFunctionDocString(), `testNonExistentFunction()`, testIllFormedMinimalDocString() 120 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 121 75: @*/ 122 76: 123 124seealso symbol 'testNonExistentFunction()' not enclosed with '`' [-fdoc-inline-list-seealso-backticks]: 125 71: References: Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. 126 72: 127> 73: .seealso: testNonExistentFunction(), testNonExistentType, 128 ^^^^^^^^^^^^^^^^^^^^^^^^^ 129 74: testIllFormedFunctionDocString(), `testNonExistentFunction()`, testIllFormedMinimalDocString() 130 75: @*/ 131 132seealso symbol 'testNonExistentType' not enclosed with '`' [-fdoc-inline-list-seealso-backticks]: 133 71: References: Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. 134 72: 135> 73: .seealso: testNonExistentFunction(), testNonExistentType, 136 ^^^^^^^^^^^^^^^^^^^ 137 74: testIllFormedFunctionDocString(), `testNonExistentFunction()`, testIllFormedMinimalDocString() 138 75: @*/ 139 140seealso symbol 'testIllFormedMinimalDocString()' not enclosed with '`' [-fdoc-inline-list-seealso-backticks]: 141 72: 142 73: .seealso: testNonExistentFunction(), testNonExistentType, 143> 74: testIllFormedFunctionDocString(), `testNonExistentFunction()`, testIllFormedMinimalDocString() 144 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 145 75: @*/ 146 76: 147 148ERROR 1: ./src/sys/tests/linter/testValidFunctionDocStrings.c:95:16 149'testIllFormedMinimalDocString' of type 'PetscErrorCode ()' (a.k.a. 'int ()') 150 93: .seealso: testNonExistentFunction(), testNonExistentType,`testNonExistentFunction() 151 94: */ 152> 95: PetscErrorCode testIllFormedMinimalDocString(void) 153 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 154 96: { 155 97: return 0; 156 157Invalid indentation (3), all regular (non-empty, non-parameter, non-seealso) text must be indented to 2 columns [-fdoc-indentation]: 158 91: References: 159 92: Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. 160> 93: .seealso: testNonExistentFunction(), testNonExistentType,`testNonExistentFunction() 161 ^^^ 162 94: */ 163 95: PetscErrorCode testIllFormedMinimalDocString(void) 164 165Missing empty line between sections, must have one before this section [-fdoc-section-spacing]: 166 91: References: 167 92: Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. 168> 93: .seealso: testNonExistentFunction(), testNonExistentType,`testNonExistentFunction() 169 94: */ 170 95: PetscErrorCode testIllFormedMinimalDocString(void) 171 172Found parameter docstring(s) but 'testIllFormedMinimalDocString()' has no parameters [-fdoc-param-list-func-parameter-documentation]: 173 83: Not Collective, Synchronous 174 84: 175> 85: input parms: 176> 86: . foo 177> 87: 178> 88: Output params: 179> 89: + bar - 180> 90: 181 91: References: 182 92: Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. 183 184seealso symbol 'testNonExistentFunction()' not enclosed with '`' [-fdoc-inline-list-seealso-backticks]: 185 91: References: 186 92: Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. 187> 93: .seealso: testNonExistentFunction(), testNonExistentType,`testNonExistentFunction() 188 ^^^^^^^^^^^^^^^^^^^^^^^^^ 189 94: */ 190 95: PetscErrorCode testIllFormedMinimalDocString(void) 191 192seealso symbol 'testNonExistentType' not enclosed with '`' [-fdoc-inline-list-seealso-backticks]: 193 91: References: 194 92: Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. 195> 93: .seealso: testNonExistentFunction(), testNonExistentType,`testNonExistentFunction() 196 ^^^^^^^^^^^^^^^^^^^ 197 94: */ 198 95: PetscErrorCode testIllFormedMinimalDocString(void) 199 200seealso symbol '`testNonExistentFunction()' not enclosed with '`' [-fdoc-inline-list-seealso-backticks]: 201 91: References: 202 92: Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. 203> 93: .seealso: testNonExistentFunction(), testNonExistentType,`testNonExistentFunction() 204 ^^^^^^^^^^^^^^^^^^^^^^^^^^ 205 94: */ 206 95: PetscErrorCode testIllFormedMinimalDocString(void) 207 208ERROR 2: ./src/sys/tests/linter/testValidFunctionDocStrings.c:118:16 209'testTerribleSpellingDocString' of type 'PetscErrorCode (PetscViewer, PetscInt, PetscScalar *)' (a.k.a. 'int (_p_PetscViewer *, int, double *)') 210 116: .zeeakso: 211 117: C@*/ 212> 118: PetscErrorCode testTerribleSpellingDocString(PetscViewer viewer, PetscInt x, PetscScalar *y) 213 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 214 119: { 215 120: return 0; 216 217Missing empty line between sections, must have one before this section [-fdoc-section-spacing]: 218 112: - -option_a - foo 219 113: - -option_b [filename][:[~]<foo,bar,baz>[:[~]bop]] - descr 220> 114: lvl: itnmediate 221 115: 222 116: .zeeakso: 223 224Docstring name 'testTerbleSpelingDocstring' does not match symbol. Assuming you meant 'testTerribleSpellingDocString' [-fdoc-synopsis-matching-symbol-name]: 225 99 : 226 100: /*@C 227> 101: testTerbleSpelingDocstring - Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do 228 ^^^^^^^^^^^^^^^^^^^^^^^^^^ 229 102: eiusmod tempor incididunt ut labore et dolore magna aliqua. 230 103: 231 232Unknown section header 'input prametirs', assuming you meant 'Input Parameter' [-fdoc-section-header-spelling]: 233 102: eiusmod tempor incididunt ut labore et dolore magna aliqua. 234 103: 235> 104: input prametirs: 236 ^^^^^^^^^^^^^^^ 237 105: + viewer - a PetsViewer 238 106: - x - a PetscInt 239 240Unknown section header 'output Psrammmetrs', assuming you meant 'Output Parameter' [-fdoc-section-header-spelling]: 241 106: - x - a PetscInt 242 107: 243> 108: output Psrammmetrs: 244 ^^^^^^^^^^^^^^^^^^ 245 109: . y - a PetscScalar pointer 246 110: 247 248Description 'a PetscInt' must be aligned to 1 space from longest (valid) argument 'viewer' [-fdoc-param-list-alignment]: 249 104: input prametirs: 250 105: + viewer - a PetsViewer 251> 106: - x - a PetscInt 252 ^^^^^^^^^^^^ 253 107: 254 108: output Psrammmetrs: 255 256Unknown section header 'optnS dtaaSE', assuming you meant 'Options Database' [-fdoc-section-header-spelling]: 257 109: . y - a PetscScalar pointer 258 110: 259> 111: optnS dtaaSE: 260 ^^^^^^^^^^^^ 261 112: - -option_a - foo 262 113: - -option_b [filename][:[~]<foo,bar,baz>[:[~]bop]] - descr 263 264First multi parameter list entry must start with '+' [-fdoc-param-list-prefix]: 265 110: 266 111: optnS dtaaSE: 267> 112: - -option_a - foo 268 ^ 269 113: - -option_b [filename][:[~]<foo,bar,baz>[:[~]bop]] - descr 270 114: lvl: itnmediate 271 272Description 'foo' must be aligned to 1 space from longest (valid) argument '-option_b [filename][:[~]<foo,bar,baz>[:[~]bop]]' [-fdoc-param-list-alignment]: 273 110: 274 111: optnS dtaaSE: 275> 112: - -option_a - foo 276 ^^^^^ 277 113: - -option_b [filename][:[~]<foo,bar,baz>[:[~]bop]] - descr 278 114: lvl: itnmediate 279 280Unknown section header 'lvl', assuming you meant 'Level' [-fdoc-section-header-spelling]: 281 112: - -option_a - foo 282 113: - -option_b [filename][:[~]<foo,bar,baz>[:[~]bop]] - descr 283> 114: lvl: itnmediate 284 ^^^ 285 115: 286 116: .zeeakso: 287 288Unknown Level subheading 'itnmediate', assuming you meant 'intermediate' [-fdoc-inline-list-level-spelling]: 289 112: - -option_a - foo 290 113: - -option_b [filename][:[~]<foo,bar,baz>[:[~]bop]] - descr 291> 114: lvl: itnmediate 292 ^^^^^^^^^^ 293 115: 294 116: .zeeakso: 295 296Unknown section header '.zeeakso', assuming you meant '.seealso' [-fdoc-section-header-spelling]: 297 114: lvl: itnmediate 298 115: 299> 116: .zeeakso: 300 ^^^^^^^^ 301 117: C@*/ 302 118: PetscErrorCode testTerribleSpellingDocString(PetscViewer viewer, PetscInt x, PetscScalar *y) 303 304ERROR 3: ./src/sys/tests/linter/testValidFunctionDocStrings.c:134:16 305'testCustomFortranInterfaceDocString' of type 'PetscErrorCode (char *******, PetscErrorCode (*)(PetscInt))' (a.k.a. 'int (char *******, int (*)(int))') 306 132: .seealso: Lorem(), `ipsum()`, dolor(), `sit(), `amet()`, consectetur(), adipiscing(), elit()` 307 133: @*/ 308> 134: PetscErrorCode testCustomFortranInterfaceDocString(char *******string, PetscErrorCode (*function_ptr)(PetscInt)) 309 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 310 135: { 311 136: return 0; 312 313Invalid comment begin line, must only contain '/*' and sowing identifier [-fdoc-sowing-chars]: 314 121: } 315 122: 316> 123: /*@ asdadsadasdas 317 ^^^^^^^^^^^^^ 318 124: testCustomFortranInterfaceDocString - Lorem ipsum dolor sit amet, consectetur adipiscing elit 319 125: 320 321Function requires custom fortran interface but missing 'C' from docstring header [-fdoc-param-list-func-fortran-interface]: 322 121: } 323 122: 324> 123: /*@ asdadsadasdas 325 ^ 326 124: testCustomFortranInterfaceDocString - Lorem ipsum dolor sit amet, consectetur adipiscing elit 327 125: 328 329./src/sys/tests/linter/testValidFunctionDocStrings.c:134:52 Note: due to char pointer 'string' of type 'char *******' 330 133: @*/ 331> 134: PetscErrorCode testCustomFortranInterfaceDocString(char *******string, PetscErrorCode (*function_ptr)(PetscInt)) 332 ^^^^^^^^^^^^^^^^^^ 333 135: { 334 335./src/sys/tests/linter/testValidFunctionDocStrings.c:134:72 Note: due to function pointer 'function_ptr' of type 'PetscErrorCode (*)(PetscInt)' (a.k.a. 'int (*)(int)') 336 133: @*/ 337> 134: PetscErrorCode testCustomFortranInterfaceDocString(char *******string, PetscErrorCode (*function_ptr)(PetscInt)) 338 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 339 135: { 340 341Description 'a char pointer' must be aligned to 1 space from longest (valid) argument 'function_ptr' [-fdoc-param-list-alignment]: 342 125: 343 126: Input Parameters: 344> 127: + string - a char pointer 345 ^^^^^^^^^^^^^^^^^ 346 128: - function_ptr - a function pointer 347 129: 348 349seealso symbol 'Lorem()' not enclosed with '`' [-fdoc-inline-list-seealso-backticks]: 350 130: Level: 351 131: 352> 132: .seealso: Lorem(), `ipsum()`, dolor(), `sit(), `amet()`, consectetur(), adipiscing(), elit()` 353 ^^^^^^^ 354 133: @*/ 355 134: PetscErrorCode testCustomFortranInterfaceDocString(char *******string, PetscErrorCode (*function_ptr)(PetscInt)) 356 357seealso symbol 'dolor()' not enclosed with '`' [-fdoc-inline-list-seealso-backticks]: 358 130: Level: 359 131: 360> 132: .seealso: Lorem(), `ipsum()`, dolor(), `sit(), `amet()`, consectetur(), adipiscing(), elit()` 361 ^^^^^^^ 362 133: @*/ 363 134: PetscErrorCode testCustomFortranInterfaceDocString(char *******string, PetscErrorCode (*function_ptr)(PetscInt)) 364 365seealso symbol '`sit()' not enclosed with '`' [-fdoc-inline-list-seealso-backticks]: 366 130: Level: 367 131: 368> 132: .seealso: Lorem(), `ipsum()`, dolor(), `sit(), `amet()`, consectetur(), adipiscing(), elit()` 369 ^^^^^^ 370 133: @*/ 371 134: PetscErrorCode testCustomFortranInterfaceDocString(char *******string, PetscErrorCode (*function_ptr)(PetscInt)) 372 373seealso symbol 'consectetur()' not enclosed with '`' [-fdoc-inline-list-seealso-backticks]: 374 130: Level: 375 131: 376> 132: .seealso: Lorem(), `ipsum()`, dolor(), `sit(), `amet()`, consectetur(), adipiscing(), elit()` 377 ^^^^^^^^^^^^^ 378 133: @*/ 379 134: PetscErrorCode testCustomFortranInterfaceDocString(char *******string, PetscErrorCode (*function_ptr)(PetscInt)) 380 381seealso symbol 'adipiscing()' not enclosed with '`' [-fdoc-inline-list-seealso-backticks]: 382 130: Level: 383 131: 384> 132: .seealso: Lorem(), `ipsum()`, dolor(), `sit(), `amet()`, consectetur(), adipiscing(), elit()` 385 ^^^^^^^^^^^^ 386 133: @*/ 387 134: PetscErrorCode testCustomFortranInterfaceDocString(char *******string, PetscErrorCode (*function_ptr)(PetscInt)) 388 389seealso symbol 'elit()`' not enclosed with '`' [-fdoc-inline-list-seealso-backticks]: 390 130: Level: 391 131: 392> 132: .seealso: Lorem(), `ipsum()`, dolor(), `sit(), `amet()`, consectetur(), adipiscing(), elit()` 393 ^^^^^^^ 394 133: @*/ 395 134: PetscErrorCode testCustomFortranInterfaceDocString(char *******string, PetscErrorCode (*function_ptr)(PetscInt)) 396 397ERROR 6: ./src/sys/tests/linter/testValidFunctionDocStrings.c:182:16 398'testAllParamsUndocumented' of type 'PetscErrorCode (PetscInt, PetscInt)' (a.k.a. 'int (int, int)') 399 180: .seealso: 400 181: @*/ 401> 182: PetscErrorCode testAllParamsUndocumented(PetscInt a, PetscInt b) 402 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 403 183: { 404 184: return testStaticFunction(); 405 406Unknown Level subheading 'beginner developer', assuming you meant 'developer' [-fdoc-inline-list-level-spelling]: 407 169: testAllParamsUndocumented - lorem 408 170: 409> 171: Level: beginner developer 410 ^^^^^^^^^^^^^^^^^^ 411 172: 412 173: Example Usage: 413 414ERROR 7: ./src/sys/tests/linter/testValidFunctionDocStrings.c:199:16 415'testParameterGrouping' of type 'PetscErrorCode (PetscInt, PetscInt, ...)' (a.k.a. 'int (int, int, ...)') 416 197: .see also: testStaticFunction() 417 198: @*/ 418> 199: PetscErrorCode testParameterGrouping(PetscInt a, PetscInt b, ...) 419 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 420 200: { 421 201: return 0; 422 423Invalid header spelling. Expected 'Input Parameters' found 'Input parameters' [-fdoc-section-header-spelling]: 424 188: testParameterGrouping ipsum 425 189: 426> 190: Input parameters: 427 ^^^^^^^^^^^^^^^^ 428 191: - a,b - some params 429 192: + nonExistentParam - this param does not exist 430 431First multi parameter list entry must start with '+' [-fdoc-param-list-prefix]: 432 189: 433 190: Input parameters: 434> 191: - a,b - some params 435 ^ 436 192: + nonExistentParam - this param does not exist 437 193: . ... - variadic arguments 438 439Multi parameter list entry must start with '.' [-fdoc-param-list-prefix]: 440 190: Input parameters: 441 191: - a,b - some params 442> 192: + nonExistentParam - this param does not exist 443 ^ 444 193: . ... - variadic arguments 445 194: 446 447Last multi parameter list entry must start with '-' [-fdoc-param-list-prefix]: 448 191: - a,b - some params 449 192: + nonExistentParam - this param does not exist 450> 193: . ... - variadic arguments 451 ^ 452 194: 453 195: Level dev 454 455Unknown section header '.see also', assuming you meant '.seealso' [-fdoc-section-header-spelling]: 456 195: Level dev 457 196: 458> 197: .see also: testStaticFunction() 459 ^^^^^^^^^ 460 198: @*/ 461 199: PetscErrorCode testParameterGrouping(PetscInt a, PetscInt b, ...) 462 463seealso symbol 'testStaticFunction()' not enclosed with '`' [-fdoc-inline-list-seealso-backticks]: 464 195: Level dev 465 196: 466> 197: .see also: testStaticFunction() 467 ^^^^^^^^^^^^^^^^^^^^ 468 198: @*/ 469 199: PetscErrorCode testParameterGrouping(PetscInt a, PetscInt b, ...) 470 471ERROR 8: ./src/sys/tests/linter/testValidFunctionDocStrings.c:218:16 472'testScatteredVerbatimBlocks' of type 'PetscErrorCode (PetscInt, PetscInt)' (a.k.a. 'int (int, int)') 473 216: .seealso: `Foo()` 474 217: @*/ 475> 218: PetscErrorCode testScatteredVerbatimBlocks(PetscInt alpha, PetscInt beta) 476 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 477 219: { 478 220: return 0; 479 480Description 'a beta' must be aligned to 1 space from longest (valid) argument 'alpha' [-fdoc-param-list-alignment]: 481 210: int a_code_block; 482 211: .ve 483> 212: - beta - a beta 484 ^^^^^^^^ 485 213: 486 214: Level: beginner 487 488ERROR 9: ./src/sys/tests/linter/testValidFunctionDocStrings.c:234:16 489'testBadParamListDescrSep' of type 'PetscErrorCode (PetscInt, PetscInt)' (a.k.a. 'int (int, int)') 490 232: .seealso: Foo() 491 233: @*/ 492> 234: PetscErrorCode testBadParamListDescrSep(PetscInt alpha, PetscInt beta) 493 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 494 235: { 495 236: return 0; 496 497Description 'an alpha' must be aligned to 1 space from longest (valid) argument 'alpha' [-fdoc-param-list-alignment]: 498 225: 499 226: Input Parameters: 500> 227: + alpha, an alpha 501 ^^^^^^^^^^ 502 228: - beta = a beta 503 229: 504 505Description 'a beta' must be aligned to 1 space from longest (valid) argument 'alpha' [-fdoc-param-list-alignment]: 506 226: Input Parameters: 507 227: + alpha, an alpha 508> 228: - beta = a beta 509 ^^^^^^^^ 510 229: 511 230: Level: beginner 512 513seealso symbol 'Foo()' not enclosed with '`' [-fdoc-inline-list-seealso-backticks]: 514 230: Level: beginner 515 231: 516> 232: .seealso: Foo() 517 ^^^^^ 518 233: @*/ 519 234: PetscErrorCode testBadParamListDescrSep(PetscInt alpha, PetscInt beta) 520 521ERROR 10: ./src/sys/tests/linter/testValidFunctionDocStrings.c:251:16 522'testBadMidSentenceColons' of type 'PetscErrorCode ()' (a.k.a. 'int ()') 523 249: .seealso: `Foo() 524 250: @*/ 525> 251: PetscErrorCode testBadMidSentenceColons(void) 526 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 527 252: { 528 253: return 0; 529 530seealso symbol '`Foo()' not enclosed with '`' [-fdoc-inline-list-seealso-backticks]: 531 247: Level: beginner 532 248: 533> 249: .seealso: `Foo() 534 ^^^^^^ 535 250: @*/ 536 251: PetscErrorCode testBadMidSentenceColons(void) 537 538ERROR 11: ./src/sys/tests/linter/testValidFunctionDocStrings.c:289:16 539'testExplicitSynopsis_Private' of type 'PetscErrorCode (PetscScalar, PetscInt, PetscReal, void *)' (a.k.a. 'int (double, int, double, void *)') 540 287: .seealso: `testExplicitSynopsisBad()` 541 288: M@*/ 542> 289: PetscErrorCode testExplicitSynopsis_Private(PetscScalar unknown, PetscInt foo, PetscReal bar, void *baz) 543 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 544 290: { 545 291: return 0; 546 547Description 'a baz' must be aligned to 1 space from longest (valid) argument 'baz' [-fdoc-param-list-alignment]: 548 281: 549 282: Output Parameter: 550> 283: . baz - a baz 551 ^^^^^^^^^^^^^^^^^^^^^ 552 284: 553 285: Level: beginner 554 555ERROR 12: ./src/sys/tests/linter/testValidFunctionDocStrings.c:310:16 556'testBadDocStringMissingChar' of type 'PetscErrorCode (PetscInt)' (a.k.a. 'int (int)') 557 308: .seealso: `testBadDocString()` 558 309: */ 559> 310: PetscErrorCode testBadDocStringMissingChar(PetscInt n) 560 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 561 311: { 562 312: return 0; 563 564Invalid docstring identifier, contains unexpected char sequence 'C', expected '/*@C'. It appears you forgot to prepend '@'? [-fdoc-sowing-chars]: 565 299: } 566 300: 567> 301: /*C testBadDocStringMissingChar - asdadsasd 568 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 569 302: 570 303: Input Parameter: 571 572Invalid comment begin line, must only contain '/*' and sowing identifier [-fdoc-sowing-chars]: 573 299: } 574 300: 575> 301: /*C testBadDocStringMissingChar - asdadsasd 576 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 577 302: 578 303: Input Parameter: 579 580ERROR 14: ./src/sys/tests/linter/testValidFunctionDocStrings.c:360:16 581'testSingleFunctionArgNotFound' of type 'PetscErrorCode (PetscScalar)' (a.k.a. 'int (double)') 582 358: 583 359: @*/ 584> 360: PetscErrorCode testSingleFunctionArgNotFound(PetscScalar some_function_arg) 585 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 586 361: { 587 362: return 0; 588 589Unknown section header 'Input parm', assuming you meant 'Input Parameter' [-fdoc-section-header-spelling]: 590 350: testSingleFunctionArgNotFound - asdasdasdasd 591 351: 592> 352: Input parm: 593 ^^^^^^^^^^ 594 353: + unrelated - A function arg 595 354: 596 597Solitary parameter list entry must start with '.' [-fdoc-param-list-prefix]: 598 351: 599 352: Input parm: 600> 353: + unrelated - A function arg 601 ^ 602 354: 603 355: lvel: dev 604 605Extra docstring parameter 'unrelated' not found in symbol parameter list [-fdoc-param-list-func-parameter-documentation]: 606 351: 607 352: Input parm: 608> 353: + unrelated - A function arg 609 ^^^^^^^^^ 610 354: 611 355: lvel: dev 612 613maybe you meant 'some_function_arg' of type 'PetscScalar' (a.k.a. 'double') 614 358: 615 359: @*/ 616> 360: PetscErrorCode testSingleFunctionArgNotFound(PetscScalar some_function_arg) 617 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 618 361: { 619 362: return 0; 620 621 622Unknown section header 'lvel', assuming you meant 'Level' [-fdoc-section-header-spelling]: 623 353: + unrelated - A function arg 624 354: 625> 355: lvel: dev 626 ^^^^ 627 356: 628 357: .seealso: `testBadDocString() 629 630seealso symbol '`testBadDocString()' not enclosed with '`' [-fdoc-inline-list-seealso-backticks]: 631 355: lvel: dev 632 356: 633> 357: .seealso: `testBadDocString() 634 ^^^^^^^^^^^^^^^^^^^ 635 358: 636 359: @*/ 637 638ERROR 15: ./src/sys/tests/linter/testValidFunctionDocStrings.c:381:16 639'testPredeclarationCursorIgnored' of type 'PetscErrorCode (int, int *)' (a.k.a. 'int (int, int *)') 640 379: */ 641 380: 642> 381: PetscErrorCode testPredeclarationCursorIgnored(int arg, int *another_arg) 643 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 644 382: { 645 383: return 0; 646 647Invalid line-spacing between docstring and the symbol it describes. The docstring must appear immediately above its target [-fdoc-symbol-spacing]: 648 378: .seealso: testPredeclarationCursorIgnored()` 649 379: */ 650> 380: 651 381: PetscErrorCode testPredeclarationCursorIgnored(int arg, int *another_arg) 652 382: { 653 654Unknown section header 'Inp Paramet', assuming you meant 'Input Parameter' [-fdoc-section-header-spelling]: 655 368: testPredeclarationCursorIgnored - the cursor above this will be ignored! 656 369: 657> 370: Inp Paramet: 658 ^^^^^^^^^^^ 659 371: . asdasd - an arg 660 372: 661 662Unknown section header 'Ouput Pameter', assuming you meant 'Output Parameter' [-fdoc-section-header-spelling]: 663 371: . asdasd - an arg 664 372: 665> 373: Ouput Pameter: 666 ^^^^^^^^^^^^^ 667 374: . another_arg_asd22 - another arg 668 375: 669 670seealso symbol 'testPredeclarationCursorIgnored()`' not enclosed with '`' [-fdoc-inline-list-seealso-backticks]: 671 376: Level: beg 672 377: 673> 378: .seealso: testPredeclarationCursorIgnored()` 674 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 675 379: */ 676 380: 677 678ERROR 16: ./src/sys/tests/linter/testValidFunctionDocStrings.c:419:16 679'testFunctionPointerArguments' of type 'PetscErrorCode (int (*)(int, double, float), int (*)(int, double, float), void (*)(int (*)(), void (*)(void (*)()), int, double, float))' (a.k.a. 'int (int (*)(int, double, float), int (*)(int, double, float), void (*)(int (*)(), void (*)(void (*)()), int, double, float))') 680 417: .seealso: `testPredeclarationCursorIgnored()` 681 418: */ 682> 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)) 683 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 684 420: { 685 421: return 0; 686 687Function requires custom fortran interface but missing 'C' from docstring header [-fdoc-param-list-func-fortran-interface]: 688 384: } 689 385: 690> 386: /*@ 691 ^ 692 387: testFunctionPointerArguments - the first set of arguments are unnamed and should be errored 693 388: 694 695./src/sys/tests/linter/testValidFunctionDocStrings.c:419:45 Note: due to function pointer 'foo' of type 'int (*)(int, double, float)' 696 418: */ 697> 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)) 698 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 699 420: { 700 701./src/sys/tests/linter/testValidFunctionDocStrings.c:419:77 Note: due to function pointer 'bar' of type 'int (*)(int, double, float)' 702 418: */ 703> 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)) 704 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 705 420: { 706 707./src/sys/tests/linter/testValidFunctionDocStrings.c:419:139 Note: due to function pointer 'baz' of type 'void (*)(int (*)(), void (*)(void (*)()), int, double, float)' 708 418: */ 709> 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)) 710 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 711 420: { 712-------------------------------------------------------------------------------------------- 713<--- LEFT ---> 714-------------------------------------------------------------------------------------------- 715ERROR 0: ./src/sys/tests/linter/testValidFunctionDocStrings.c:77:16 716'testIllFormedFunctionDocString' of type 'PetscErrorCode (PetscViewer, PetscInt, PetscScalar *, PetscBool)' (a.k.a. 'int (_p_PetscViewer *, int, double *, PetscBool)') 717 75: @*/ 718 76: 719> 77: PetscErrorCode testIllFormedFunctionDocString(PetscViewer viewer, PetscInt x, PetscScalar *y, PetscBool cond) 720 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 721 78: { 722 79: return 0; 723 724Sowing treats all lines ending with ':' as header, are you sure 'qui officia deserunt mollit [...]' qualifies? Use '\:' to escape the colon if not [-fdoc-section-header-fishy-header]: 725 58: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut 726 59: labore et dolore magna aliqua. Excepteur sint occaecat cupidatat non proident, sunt in culpa 727> 60: qui officia deserunt mollit anim id est laborum as follows: 728 ^ 729 61: 730 62: Notes Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor 731 732Line seems to be a section header but missing ':', did you mean 'Notes:'? [-fdoc-section-header-maybe-header]: 733 60: qui officia deserunt mollit anim id est laborum as follows: 734 61: 735> 62: Notes Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor 736 ^^^^^ 737 63: incididunt ut labore et dolore magna aliqua. Excepteur sint occaecat cupidatat non proident, 738 64: sunt in culpa qui officia deserunt mollit anim id est laborum example. 739 740Sowing treats all lines ending with ':' as header, are you sure 'qui officia deserunt mollit [...]' qualifies? Use '\:' to escape the colon if not [-fdoc-section-header-fishy-header]: 741 67: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut 742 68: labore et dolore magna aliqua. Excepteur sint occaecat cupidatat non proident, sunt in culpa 743> 69: qui officia deserunt mollit anim id est laborum instance: 744 ^ 745 70: 746 71: References: Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. 747 748Docstring name 'someOtherFunctionName' does not match symbol name 'testIllFormedFunctionDocString' [-fdoc-synopsis-matching-symbol-name]: 749 33: 750 34: /*@C Lorem ipsum dolor sit amet 751> 35: someOtherFunctionName - Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do 752 ^^^^^^^^^^^^^^^^^^^^^ 753 36: eiusmod tempor incididunt ut labore et dolore magna aliqua. Excepteur sint occaecat cupidatat 754 37: non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Sed ut 755 756Synopsis for 'testIllFormedFunctionDocString' is too long (must be at most 250 characters or 40 words), consider moving it to Notes. If you can't explain it simply, then you don't understand it well enough! [-fdoc-synopsis-verbose-description]: 757 33: 758 34: /*@C Lorem ipsum dolor sit amet 759> 35: someOtherFunctionName - Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do 760> 36: eiusmod tempor incididunt ut labore et dolore magna aliqua. Excepteur sint occaecat cupidatat 761> 37: non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Sed ut 762> 38: perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, 763> 39: totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae 764> 40: vitae dicta sunt explicabo. 765> 41: 766> 42: Not Collective, Synchronous 767> 43: 768 44: Input Parameters: 769 45: + viewer - a PetscViewer 770 771Extra docstring parameter 'cnd' not found in symbol parameter list [-fdoc-param-list-func-parameter-documentation]: 772 47: Output Parameter: 773 48: - y - a pointer 774> 49: + cnd - a boolean 775 ^^^ 776 50: . z - a nonexistent parameter 777 51: 778 779maybe you meant 'cond' of type 'PetscBool' 780 75: @*/ 781 76: 782> 77: PetscErrorCode testIllFormedFunctionDocString(PetscViewer viewer, PetscInt x, PetscScalar *y, PetscBool cond) 783 ^^^^^^^^^^^^^^ 784 78: { 785 79: return 0; 786 787 788Heading must appear alone on a line, any content must be on the next line [-fdoc-section-header-solitary]: 789 60: qui officia deserunt mollit anim id est laborum as follows: 790 61: 791> 62: Notes Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor 792 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 793 63: incididunt ut labore et dolore magna aliqua. Excepteur sint occaecat cupidatat non proident, 794 64: sunt in culpa qui officia deserunt mollit anim id est laborum example. 795 796Multiple 'Level' subheadings. Much like Highlanders, there can only be one [-fdoc-section-header-unique]: 797 50: . z - a nonexistent parameter 798 51: 799> 52: level: Lorem ipsum dolor sit amet 800 ^^^^^ 801 53: 802> 54: Level: 803 ^^^^^ 804 55: Beginner 805 56: 806 807Unknown Level subheading 'Lorem ipsum dolor sit amet', expected one of beginner, intermediate, advanced, developer, or deprecated [-fdoc-inline-list-level-spelling]: 808 50: . z - a nonexistent parameter 809 51: 810> 52: level: Lorem ipsum dolor sit amet 811 ^^^^^^^^^^^^^^^^^^^^^^^^^^ 812 53: 813 54: Level: 814 815ERROR 1: ./src/sys/tests/linter/testValidFunctionDocStrings.c:95:16 816'testIllFormedMinimalDocString' of type 'PetscErrorCode ()' (a.k.a. 'int ()') 817 93: .seealso: testNonExistentFunction(), testNonExistentType,`testNonExistentFunction() 818 94: */ 819> 95: PetscErrorCode testIllFormedMinimalDocString(void) 820 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 821 96: { 822 97: return 0; 823 824Invalid comment begin line, does not contain sowing identifier. Expected '/*@' for functions [-fdoc-sowing-chars]: 825 80: } 826 81: 827> 82: /* 828 ^^ 829 83: Not Collective, Synchronous 830 84: 831 832Docstring missing synopsis [-fdoc-synopsis-missing-description]: 833 81: 834 82: /* 835> 83: Not Collective, Synchronous 836> 84: 837 85: input parms: 838 86: . foo 839 840./src/sys/tests/linter/testValidFunctionDocStrings.c:83:1 Note: Expected 'testIllFormedMinimalDocString - a very useful description' 841 842Required section 'Level' not found [-fdoc-section-header-missing]: 843 80: } 844 81: 845> 82: /* 846> 83: Not Collective, Synchronous 847> 84: 848> 85: input parms: 849> 86: . foo 850> 87: 851> 88: Output params: 852> 89: + bar - 853> 90: 854> 91: References: 855> 92: Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. 856> 93: .seealso: testNonExistentFunction(), testNonExistentType,`testNonExistentFunction() 857> 94: */ 858 95: PetscErrorCode testIllFormedMinimalDocString(void) 859 96: { 860 861ERROR 2: ./src/sys/tests/linter/testValidFunctionDocStrings.c:118:16 862'testTerribleSpellingDocString' of type 'PetscErrorCode (PetscViewer, PetscInt, PetscScalar *)' (a.k.a. 'int (_p_PetscViewer *, int, double *)') 863 116: .zeeakso: 864 117: C@*/ 865> 118: PetscErrorCode testTerribleSpellingDocString(PetscViewer viewer, PetscInt x, PetscScalar *y) 866 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 867 119: { 868 120: return 0; 869 870Section appears to be empty; while I'm all for a good mystery, you should probably elaborate here [-fdoc-section-barren]: 871 114: lvl: itnmediate 872 115: 873> 116: .zeeakso: 874 ^^^^^^^^^ 875 117: C@*/ 876 118: PetscErrorCode testTerribleSpellingDocString(PetscViewer viewer, PetscInt x, PetscScalar *y) 877 878ERROR 3: ./src/sys/tests/linter/testValidFunctionDocStrings.c:134:16 879'testCustomFortranInterfaceDocString' of type 'PetscErrorCode (char *******, PetscErrorCode (*)(PetscInt))' (a.k.a. 'int (char *******, int (*)(int))') 880 132: .seealso: Lorem(), `ipsum()`, dolor(), `sit(), `amet()`, consectetur(), adipiscing(), elit()` 881 133: @*/ 882> 134: PetscErrorCode testCustomFortranInterfaceDocString(char *******string, PetscErrorCode (*function_ptr)(PetscInt)) 883 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 884 135: { 885 136: return 0; 886 887Section appears to be empty; while I'm all for a good mystery, you should probably elaborate here [-fdoc-section-barren]: 888 128: - function_ptr - a function pointer 889 129: 890> 130: Level: 891> 131: 892 132: .seealso: Lorem(), `ipsum()`, dolor(), `sit(), `amet()`, consectetur(), adipiscing(), elit()` 893 133: @*/ 894 895ERROR 4: ./src/sys/tests/linter/testValidFunctionDocStrings.c:151:16 896'testInternFunction' of type 'PetscErrorCode ()' (a.k.a. 'int ()') 897 149: .seealso: function() 898 150: @*/ 899> 151: PetscErrorCode testInternFunction() 900 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 901 152: { 902 153: return 0; 903 904A sowing docstring for a symbol with internal linkage is pointless [-fdoc-internal-linkage]!: 905 142: PETSC_INTERN PetscErrorCode testInternFunction(); 906 143: 907> 144: /*@ 908> 145: testInternFunction - an internal function 909> 146: 910> 147: Level: developer 911> 148: 912> 149: .seealso: function() 913> 150: @*/ 914 151: PetscErrorCode testInternFunction() 915 152: { 916 917./src/sys/tests/linter/testValidFunctionDocStrings.c:142:1 Note: 'testInternFunction()' is declared 'PETSC_INTERN' at ./src/sys/tests/linter/testValidFunctionDocStrings.c:142:1 918'hidden' of type '' 919 140: void function() { } 920 141: 921> 142: PETSC_INTERN PetscErrorCode testInternFunction(); 922 ^^^^^^^^^^^^ 923 143: 924 144: /*@ 925 926 927./src/sys/tests/linter/testValidFunctionDocStrings.c:144:1 Note: If this docstring is meant as developer-only documentation, remove the sowing chars from the docstring declaration. The linter will then ignore this docstring. 928 929./src/sys/tests/linter/testValidFunctionDocStrings.c:144:3 Note: Sowing chars declared here: 930 142: PETSC_INTERN PetscErrorCode testInternFunction(); 931 143: 932> 144: /*@ 933 ^ 934 145: testInternFunction - an internal function 935 146: 936 937ERROR 5: ./src/sys/tests/linter/testValidFunctionDocStrings.c:163:23 938'testStaticFunction' of type 'PetscErrorCode ()' (a.k.a. 'int ()') 939 161: .seealso: function() 940 162: @*/ 941> 163: static PetscErrorCode testStaticFunction() 942 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 943 164: { 944 165: return 0; 945 946A sowing docstring for a symbol with internal linkage is pointless [-fdoc-internal-linkage]!: 947 154: } 948 155: 949> 156: /*@ 950> 157: testStaticFunction - an internal function 951> 158: 952> 159: Level: developer 953> 160: 954> 161: .seealso: function() 955> 162: @*/ 956 163: static PetscErrorCode testStaticFunction() 957 164: { 958 959./src/sys/tests/linter/testValidFunctionDocStrings.c:163:1 Note: 'testStaticFunction()' is declared 'STATIC' at ./src/sys/tests/linter/testValidFunctionDocStrings.c:163:23 960'testStaticFunction' of type 'PetscErrorCode ()' (a.k.a. 'int ()') 961 161: .seealso: function() 962 162: @*/ 963> 163: static PetscErrorCode testStaticFunction() 964 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 965 164: { 966 165: return 0; 967 968 969./src/sys/tests/linter/testValidFunctionDocStrings.c:156:1 Note: If this docstring is meant as developer-only documentation, remove the sowing chars from the docstring declaration. The linter will then ignore this docstring. 970 971./src/sys/tests/linter/testValidFunctionDocStrings.c:156:3 Note: Sowing chars declared here: 972 154: } 973 155: 974> 156: /*@ 975 ^ 976 157: testStaticFunction - an internal function 977 158: 978 979ERROR 6: ./src/sys/tests/linter/testValidFunctionDocStrings.c:182:16 980'testAllParamsUndocumented' of type 'PetscErrorCode (PetscInt, PetscInt)' (a.k.a. 'int (int, int)') 981 180: .seealso: 982 181: @*/ 983> 182: PetscErrorCode testAllParamsUndocumented(PetscInt a, PetscInt b) 984 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 985 183: { 986 184: return testStaticFunction(); 987 988Symbol parameters are all undocumented [-fdoc-param-list-func-parameter-documentation]: 989 166: } 990 167: 991> 168: /*@ 992> 169: testAllParamsUndocumented - lorem 993> 170: 994> 171: Level: beginner developer 995> 172: 996> 173: Example Usage: 997> 174: .vb 998> 175: int a; 999> 176: double multiline; 1000> 177: char codeBlock; 1001> 178: .ve 1002> 179: 1003> 180: .seealso: 1004> 181: @*/ 1005 182: PetscErrorCode testAllParamsUndocumented(PetscInt a, PetscInt b) 1006 183: { 1007 1008./src/sys/tests/linter/testValidFunctionDocStrings.c:182:42 Note: Parameters defined here: 1009 180: .seealso: 1010 181: @*/ 1011> 182: PetscErrorCode testAllParamsUndocumented(PetscInt a, PetscInt b) 1012 ^^^^^^^^^^^^^^^^^^^^^^ 1013 183: { 1014 184: return testStaticFunction(); 1015 1016Section appears to be empty; while I'm all for a good mystery, you should probably elaborate here [-fdoc-section-barren]: 1017 178: .ve 1018 179: 1019> 180: .seealso: 1020 ^^^^^^^^^ 1021 181: @*/ 1022 182: PetscErrorCode testAllParamsUndocumented(PetscInt a, PetscInt b) 1023 1024ERROR 7: ./src/sys/tests/linter/testValidFunctionDocStrings.c:199:16 1025'testParameterGrouping' of type 'PetscErrorCode (PetscInt, PetscInt, ...)' (a.k.a. 'int (int, int, ...)') 1026 197: .see also: testStaticFunction() 1027 198: @*/ 1028> 199: PetscErrorCode testParameterGrouping(PetscInt a, PetscInt b, ...) 1029 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1030 200: { 1031 201: return 0; 1032 1033Line seems to be a section header but missing ':', did you mean 'Level:'? [-fdoc-section-header-maybe-header]: 1034 193: . ... - variadic arguments 1035 194: 1036> 195: Level dev 1037 ^^^^^^^^^ 1038 196: 1039 197: .see also: testStaticFunction() 1040 1041Synopsis seems to be missing a description separator; I suspect you may be using ' ' as a separator instead of '-'. Expected 'testParameterGrouping - ipsum' [-fdoc-synopsis-wrong-description-separator]: 1042 186: 1043 187: /*@ 1044> 188: testParameterGrouping ipsum 1045 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1046 189: 1047 190: Input parameters: 1048 1049Each parameter entry must be documented separately on its own line [-fdoc-param-list-solitary-parameter]: 1050 189: 1051 190: Input parameters: 1052> 191: - a,b - some params 1053 ^^^ 1054 192: + nonExistentParam - this param does not exist 1055 193: . ... - variadic arguments 1056 1057./src/sys/tests/linter/testValidFunctionDocStrings.c:191:3 Note: variable argument lists should be documented in notes 1058 1059Extra docstring parameter 'nonExistentParam' not found in symbol parameter list [-fdoc-param-list-func-parameter-documentation]: 1060 190: Input parameters: 1061 191: - a,b - some params 1062> 192: + nonExistentParam - this param does not exist 1063 ^^^^^^^^^^^^^^^^ 1064 193: . ... - variadic arguments 1065 194: 1066 1067Extra docstring parameter '...' not found in symbol parameter list [-fdoc-param-list-func-parameter-documentation]: 1068 191: - a,b - some params 1069 192: + nonExistentParam - this param does not exist 1070> 193: . ... - variadic arguments 1071 ^^^ 1072 194: 1073 195: Level dev 1074 1075Unknown Level subheading 'dev', expected one of beginner, intermediate, advanced, developer, or deprecated [-fdoc-inline-list-level-spelling]: 1076 193: . ... - variadic arguments 1077 194: 1078> 195: Level dev 1079 ^^^ 1080 196: 1081 197: .see also: testStaticFunction() 1082 1083ERROR 9: ./src/sys/tests/linter/testValidFunctionDocStrings.c:234:16 1084'testBadParamListDescrSep' of type 'PetscErrorCode (PetscInt, PetscInt)' (a.k.a. 'int (int, int)') 1085 232: .seealso: Foo() 1086 233: @*/ 1087> 234: PetscErrorCode testBadParamListDescrSep(PetscInt alpha, PetscInt beta) 1088 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1089 235: { 1090 236: return 0; 1091 1092Parameters seems to be missing a description separator; I suspect you may be using ',' as a separator instead of '-'. Expected 'alpha - an alpha' [-fdoc-param-list-wrong-description-separator]: 1093 225: 1094 226: Input Parameters: 1095> 227: + alpha, an alpha 1096 ^^^^^^^^^^^^^^^^^ 1097 228: - beta = a beta 1098 229: 1099 1100Parameters seems to be missing a description separator; I suspect you may be using '=' as a separator instead of '-'. Expected 'beta - a beta' [-fdoc-param-list-wrong-description-separator]: 1101 226: Input Parameters: 1102 227: + alpha, an alpha 1103> 228: - beta = a beta 1104 ^^^^^^^^^^^^^^^ 1105 229: 1106 230: Level: beginner 1107 1108ERROR 10: ./src/sys/tests/linter/testValidFunctionDocStrings.c:251:16 1109'testBadMidSentenceColons' of type 'PetscErrorCode ()' (a.k.a. 'int ()') 1110 249: .seealso: `Foo() 1111 250: @*/ 1112> 251: PetscErrorCode testBadMidSentenceColons(void) 1113 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1114 252: { 1115 253: return 0; 1116 1117Sowing treats all lines ending with ':' as header, are you sure 'testBadMidSentenceColons - Lorem:' qualifies? Use '\:' to escape the colon if not [-fdoc-section-header-fishy-header]: 1118 238: 1119 239: /*@ 1120> 240: testBadMidSentenceColons - Lorem: 1121 ^ 1122 241: 1123 242: Notes: 1124 1125Sowing treats all lines ending with ':' as header, are you sure 'qui officia: deserunt mollit: [...]' qualifies? Use '\:' to escape the colon if not [-fdoc-section-header-fishy-header]: 1126 243: Lorem ipsum dolor sit amet:, consectetur adipiscing elit: sed do: eiusmod tempor: incididunt ut 1127 244: labore et dolore: magna aliqua: Excepteur: sint occaecat cupidatat non proident, sunt: in culpa 1128> 245: qui officia: deserunt mollit: anim id est: laborum as follows: 1129 ^ 1130 246: 1131 247: Level: beginner 1132 1133ERROR 11: ./src/sys/tests/linter/testValidFunctionDocStrings.c:289:16 1134'testExplicitSynopsis_Private' of type 'PetscErrorCode (PetscScalar, PetscInt, PetscReal, void *)' (a.k.a. 'int (double, int, double, void *)') 1135 287: .seealso: `testExplicitSynopsisBad()` 1136 288: M@*/ 1137> 289: PetscErrorCode testExplicitSynopsis_Private(PetscScalar unknown, PetscInt foo, PetscReal bar, void *baz) 1138 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1139 290: { 1140 291: return 0; 1141 1142Undocumented parameter 'unknown' not found in parameter section [-fdoc-param-list-func-parameter-documentation]: 1143 276: PetscErrorCode testExplicitSynopsis(PetscInt foo, PetscReal bar, void *baz) 1144 277: 1145> 278: Input Parameters: 1146> 279: + foo - a foo 1147> 280: - bar - a bar 1148> 281: 1149> 282: Output Parameter: 1150> 283: . baz - a baz 1151> 284: 1152 285: Level: beginner 1153 286: 1154 1155./src/sys/tests/linter/testValidFunctionDocStrings.c:289:45 Note: Parameter 'unknown' defined here: 1156 288: M@*/ 1157> 289: PetscErrorCode testExplicitSynopsis_Private(PetscScalar unknown, PetscInt foo, PetscReal bar, void *baz) 1158 ^^^^^^^^^^^^^^^^^^^ 1159 290: { 1160 1161ERROR 12: ./src/sys/tests/linter/testValidFunctionDocStrings.c:310:16 1162'testBadDocStringMissingChar' of type 'PetscErrorCode (PetscInt)' (a.k.a. 'int (int)') 1163 308: .seealso: `testBadDocString()` 1164 309: */ 1165> 310: PetscErrorCode testBadDocStringMissingChar(PetscInt n) 1166 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1167 311: { 1168 312: return 0; 1169 1170Docstring missing synopsis [-fdoc-synopsis-missing-description]: 1171 300: 1172 301: /*C testBadDocStringMissingChar - asdadsasd 1173> 302: 1174 303: Input Parameter: 1175 304: . n - the n 1176 1177./src/sys/tests/linter/testValidFunctionDocStrings.c:302:1 Note: Expected 'testBadDocStringMissingChar - a very useful description' 1178 1179ERROR 13: ./src/sys/tests/linter/testValidFunctionDocStrings.c:325:16 1180'testBadDocStringCharOutOfOrder' of type 'PetscErrorCode (PetscInt)' (a.k.a. 'int (int)') 1181 323: .seealso: `testBadDocString()` 1182 324: */ 1183> 325: PetscErrorCode testBadDocStringCharOutOfOrder(PetscInt n) 1184 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1185 326: { 1186 327: return 0; 1187 1188Invalid docstring identifier, contains unexpected char sequence 'C@', expected '/*@C'. Did you put it in the wrong order? [-fdoc-sowing-chars]: 1189 313: } 1190 314: 1191> 315: /*C@ 1192 ^^^^ 1193 316: testBadDocStringCharOutOfOrder - asdadsasd 1194 317: 1195 1196ERROR 15: ./src/sys/tests/linter/testValidFunctionDocStrings.c:381:16 1197'testPredeclarationCursorIgnored' of type 'PetscErrorCode (int, int *)' (a.k.a. 'int (int, int *)') 1198 379: */ 1199 380: 1200> 381: PetscErrorCode testPredeclarationCursorIgnored(int arg, int *another_arg) 1201 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1202 382: { 1203 383: return 0; 1204 1205Invalid comment begin line, does not contain sowing identifier. Expected '/*@' for functions [-fdoc-sowing-chars]: 1206 365: extern PetscErrorCode testPredeclarationCursorIgnored(int, int *); 1207 366: 1208> 367: /* 1209 ^^ 1210 368: testPredeclarationCursorIgnored - the cursor above this will be ignored! 1211 369: 1212 1213Extra docstring parameter 'asdasd' not found in symbol parameter list [-fdoc-param-list-func-parameter-documentation]: 1214 369: 1215 370: Inp Paramet: 1216> 371: . asdasd - an arg 1217 ^^^^^^ 1218 372: 1219 373: Ouput Pameter: 1220 1221Extra docstring parameter 'another_arg_asd22' not found in symbol parameter list [-fdoc-param-list-func-parameter-documentation]: 1222 372: 1223 373: Ouput Pameter: 1224> 374: . another_arg_asd22 - another arg 1225 ^^^^^^^^^^^^^^^^^ 1226 375: 1227 376: Level: beg 1228 1229maybe you meant 'another_arg' of type 'int *' 1230 379: */ 1231 380: 1232> 381: PetscErrorCode testPredeclarationCursorIgnored(int arg, int *another_arg) 1233 ^^^^^^^^^^^^^^^^ 1234 382: { 1235 383: return 0; 1236 1237 1238Undocumented parameter 'arg' not found in parameter section [-fdoc-param-list-func-parameter-documentation]: 1239 368: testPredeclarationCursorIgnored - the cursor above this will be ignored! 1240 369: 1241> 370: Inp Paramet: 1242> 371: . asdasd - an arg 1243> 372: 1244> 373: Ouput Pameter: 1245> 374: . another_arg_asd22 - another arg 1246> 375: 1247 376: Level: beg 1248 377: 1249 1250./src/sys/tests/linter/testValidFunctionDocStrings.c:381:48 Note: Parameter 'arg' defined here: 1251 380: 1252> 381: PetscErrorCode testPredeclarationCursorIgnored(int arg, int *another_arg) 1253 ^^^^^^^ 1254 382: { 1255 1256Unknown Level subheading 'beg', expected one of beginner, intermediate, advanced, developer, or deprecated [-fdoc-inline-list-level-spelling]: 1257 374: . another_arg_asd22 - another arg 1258 375: 1259> 376: Level: beg 1260 ^^^ 1261 377: 1262 378: .seealso: testPredeclarationCursorIgnored()` 1263 1264ERROR 16: ./src/sys/tests/linter/testValidFunctionDocStrings.c:419:16 1265'testFunctionPointerArguments' of type 'PetscErrorCode (int (*)(int, double, float), int (*)(int, double, float), void (*)(int (*)(), void (*)(void (*)()), int, double, float))' (a.k.a. 'int (int (*)(int, double, float), int (*)(int, double, float), void (*)(int (*)(), void (*)(void (*)()), int, double, float))') 1266 417: .seealso: `testPredeclarationCursorIgnored()` 1267 418: */ 1268> 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)) 1269 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1270 420: { 1271 421: return 0; 1272 1273Extra docstring parameter 'foo_parm1' not found in symbol parameter list [-fdoc-param-list-func-parameter-documentation]: 1274 393: 1275 394: Calling sequence of foo: 1276> 395: + foo_parm1 - an int 1277 ^^^^^^^^^ 1278 396: . foo_parm2 - a double 1279 397: - foo_parm3 - a float 1280 1281Extra docstring parameter 'foo_parm2' not found in symbol parameter list [-fdoc-param-list-func-parameter-documentation]: 1282 394: Calling sequence of foo: 1283 395: + foo_parm1 - an int 1284> 396: . foo_parm2 - a double 1285 ^^^^^^^^^ 1286 397: - foo_parm3 - a float 1287 398: 1288 1289Extra docstring parameter 'foo_parm3' not found in symbol parameter list [-fdoc-param-list-func-parameter-documentation]: 1290 395: + foo_parm1 - an int 1291 396: . foo_parm2 - a double 1292> 397: - foo_parm3 - a float 1293 ^^^^^^^^^ 1294 398: 1295 399: Calling sequence of bar: 1296--------------------------------------------------------------------------------------------