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 713ERROR 17: ./src/sys/tests/linter/testValidFunctionDocStrings.c:448:16 714'testIllFormedDeprecated' of type 'PetscErrorCode ()' (a.k.a. 'int ()') 715 446: .seealso: `testDeprecated()` 716 447: */ 717> 448: PetscErrorCode testIllFormedDeprecated(void) 718 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 719 449: { 720 450: return PETSC_SUCCESS; 721 722Found parameter docstring(s) but 'testIllFormedDeprecated()' has no parameters [-fdoc-param-list-func-parameter-documentation]: 723 437: testIllFormedDeprecated - check that deprecated (since VERSION) works 724 438: 725> 439: Input Parameters: 726> 440: + foo - a nonexistent foo 727> 441: . bar - a nonexistent bar 728> 442: - baz - a nonexistent baz 729> 443: 730 444: Level: dpcrtd (since 3.18.5) 731 445: 732 733Unknown Level subheading 'dpcrtd', assuming you meant 'deprecated' [-fdoc-inline-list-level-spelling]: 734 442: - baz - a nonexistent baz 735 443: 736> 444: Level: dpcrtd (since 3.18.5) 737 ^^^^^^ 738 445: 739 446: .seealso: `testDeprecated()` 740-------------------------------------------------------------------------------------------- 741<--- LEFT ---> 742-------------------------------------------------------------------------------------------- 743ERROR 0: ./src/sys/tests/linter/testValidFunctionDocStrings.c:77:16 744'testIllFormedFunctionDocString' of type 'PetscErrorCode (PetscViewer, PetscInt, PetscScalar *, PetscBool)' (a.k.a. 'int (_p_PetscViewer *, int, double *, PetscBool)') 745 75: @*/ 746 76: 747> 77: PetscErrorCode testIllFormedFunctionDocString(PetscViewer viewer, PetscInt x, PetscScalar *y, PetscBool cond) 748 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 749 78: { 750 79: return 0; 751 752Sowing 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]: 753 58: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut 754 59: labore et dolore magna aliqua. Excepteur sint occaecat cupidatat non proident, sunt in culpa 755> 60: qui officia deserunt mollit anim id est laborum as follows: 756 ^ 757 61: 758 62: Notes Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor 759 760Line seems to be a section header but missing ':', did you mean 'Notes:'? [-fdoc-section-header-maybe-header]: 761 60: qui officia deserunt mollit anim id est laborum as follows: 762 61: 763> 62: Notes Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor 764 ^^^^^ 765 63: incididunt ut labore et dolore magna aliqua. Excepteur sint occaecat cupidatat non proident, 766 64: sunt in culpa qui officia deserunt mollit anim id est laborum example. 767 768Sowing 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]: 769 67: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut 770 68: labore et dolore magna aliqua. Excepteur sint occaecat cupidatat non proident, sunt in culpa 771> 69: qui officia deserunt mollit anim id est laborum instance: 772 ^ 773 70: 774 71: References: Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. 775 776Docstring name 'someOtherFunctionName' does not match symbol name 'testIllFormedFunctionDocString' [-fdoc-synopsis-matching-symbol-name]: 777 33: 778 34: /*@C Lorem ipsum dolor sit amet 779> 35: someOtherFunctionName - Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do 780 ^^^^^^^^^^^^^^^^^^^^^ 781 36: eiusmod tempor incididunt ut labore et dolore magna aliqua. Excepteur sint occaecat cupidatat 782 37: non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Sed ut 783 784Synopsis 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]: 785 33: 786 34: /*@C Lorem ipsum dolor sit amet 787> 35: someOtherFunctionName - Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do 788> 36: eiusmod tempor incididunt ut labore et dolore magna aliqua. Excepteur sint occaecat cupidatat 789> 37: non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Sed ut 790> 38: perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, 791> 39: totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae 792> 40: vitae dicta sunt explicabo. 793> 41: 794> 42: Not Collective, Synchronous 795> 43: 796 44: Input Parameters: 797 45: + viewer - a PetscViewer 798 799Extra docstring parameter 'cnd' not found in symbol parameter list [-fdoc-param-list-func-parameter-documentation]: 800 47: Output Parameter: 801 48: - y - a pointer 802> 49: + cnd - a boolean 803 ^^^ 804 50: . z - a nonexistent parameter 805 51: 806 807maybe you meant 'cond' of type 'PetscBool' 808 75: @*/ 809 76: 810> 77: PetscErrorCode testIllFormedFunctionDocString(PetscViewer viewer, PetscInt x, PetscScalar *y, PetscBool cond) 811 ^^^^^^^^^^^^^^ 812 78: { 813 79: return 0; 814 815 816Heading must appear alone on a line, any content must be on the next line [-fdoc-section-header-solitary]: 817 60: qui officia deserunt mollit anim id est laborum as follows: 818 61: 819> 62: Notes Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor 820 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 821 63: incididunt ut labore et dolore magna aliqua. Excepteur sint occaecat cupidatat non proident, 822 64: sunt in culpa qui officia deserunt mollit anim id est laborum example. 823 824Multiple 'Level' subheadings. Much like Highlanders, there can only be one [-fdoc-section-header-unique]: 825 50: . z - a nonexistent parameter 826 51: 827> 52: level: Lorem ipsum dolor sit amet 828 ^^^^^ 829 53: 830> 54: Level: 831 ^^^^^ 832 55: Beginner 833 56: 834 835Unknown Level subheading 'Lorem ipsum dolor sit amet', expected one of beginner, intermediate, advanced, developer, or deprecated [-fdoc-inline-list-level-spelling]: 836 50: . z - a nonexistent parameter 837 51: 838> 52: level: Lorem ipsum dolor sit amet 839 ^^^^^ 840 53: 841 54: Level: 842 843ERROR 1: ./src/sys/tests/linter/testValidFunctionDocStrings.c:95:16 844'testIllFormedMinimalDocString' of type 'PetscErrorCode ()' (a.k.a. 'int ()') 845 93: .seealso: testNonExistentFunction(), testNonExistentType,`testNonExistentFunction() 846 94: */ 847> 95: PetscErrorCode testIllFormedMinimalDocString(void) 848 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 849 96: { 850 97: return 0; 851 852Invalid comment begin line, does not contain sowing identifier. Expected '/*@' for functions [-fdoc-sowing-chars]: 853 80: } 854 81: 855> 82: /* 856 ^^ 857 83: Not Collective, Synchronous 858 84: 859 860Docstring missing synopsis [-fdoc-synopsis-missing-description]: 861 81: 862 82: /* 863> 83: Not Collective, Synchronous 864> 84: 865 85: input parms: 866 86: . foo 867 868./src/sys/tests/linter/testValidFunctionDocStrings.c:83:1 Note: Expected 'testIllFormedMinimalDocString - a very useful description' 869 870Required section 'Level' not found [-fdoc-section-header-missing]: 871 80: } 872 81: 873> 82: /* 874> 83: Not Collective, Synchronous 875> 84: 876> 85: input parms: 877> 86: . foo 878> 87: 879> 88: Output params: 880> 89: + bar - 881> 90: 882> 91: References: 883> 92: Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. 884> 93: .seealso: testNonExistentFunction(), testNonExistentType,`testNonExistentFunction() 885> 94: */ 886 95: PetscErrorCode testIllFormedMinimalDocString(void) 887 96: { 888 889ERROR 2: ./src/sys/tests/linter/testValidFunctionDocStrings.c:118:16 890'testTerribleSpellingDocString' of type 'PetscErrorCode (PetscViewer, PetscInt, PetscScalar *)' (a.k.a. 'int (_p_PetscViewer *, int, double *)') 891 116: .zeeakso: 892 117: C@*/ 893> 118: PetscErrorCode testTerribleSpellingDocString(PetscViewer viewer, PetscInt x, PetscScalar *y) 894 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 895 119: { 896 120: return 0; 897 898Section appears to be empty; while I'm all for a good mystery, you should probably elaborate here [-fdoc-section-barren]: 899 114: lvl: itnmediate 900 115: 901> 116: .zeeakso: 902 ^^^^^^^^^ 903 117: C@*/ 904 118: PetscErrorCode testTerribleSpellingDocString(PetscViewer viewer, PetscInt x, PetscScalar *y) 905 906ERROR 3: ./src/sys/tests/linter/testValidFunctionDocStrings.c:134:16 907'testCustomFortranInterfaceDocString' of type 'PetscErrorCode (char *******, PetscErrorCode (*)(PetscInt))' (a.k.a. 'int (char *******, int (*)(int))') 908 132: .seealso: Lorem(), `ipsum()`, dolor(), `sit(), `amet()`, consectetur(), adipiscing(), elit()` 909 133: @*/ 910> 134: PetscErrorCode testCustomFortranInterfaceDocString(char *******string, PetscErrorCode (*function_ptr)(PetscInt)) 911 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 912 135: { 913 136: return 0; 914 915Section appears to be empty; while I'm all for a good mystery, you should probably elaborate here [-fdoc-section-barren]: 916 128: - function_ptr - a function pointer 917 129: 918> 130: Level: 919> 131: 920 132: .seealso: Lorem(), `ipsum()`, dolor(), `sit(), `amet()`, consectetur(), adipiscing(), elit()` 921 133: @*/ 922 923ERROR 4: ./src/sys/tests/linter/testValidFunctionDocStrings.c:151:16 924'testInternFunction' of type 'PetscErrorCode ()' (a.k.a. 'int ()') 925 149: .seealso: function() 926 150: @*/ 927> 151: PetscErrorCode testInternFunction() 928 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 929 152: { 930 153: return 0; 931 932A sowing docstring for a symbol with internal linkage is pointless [-fdoc-internal-linkage]!: 933 142: PETSC_INTERN PetscErrorCode testInternFunction(); 934 143: 935> 144: /*@ 936> 145: testInternFunction - an internal function 937> 146: 938> 147: Level: developer 939> 148: 940> 149: .seealso: function() 941> 150: @*/ 942 151: PetscErrorCode testInternFunction() 943 152: { 944 945./src/sys/tests/linter/testValidFunctionDocStrings.c:142:1 Note: 'testInternFunction()' is declared 'PETSC_INTERN' at ./src/sys/tests/linter/testValidFunctionDocStrings.c:142:1 946'hidden' of type '' 947 140: void function() { } 948 141: 949> 142: PETSC_INTERN PetscErrorCode testInternFunction(); 950 ^^^^^^^^^^^^ 951 143: 952 144: /*@ 953 954 955./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. 956 957./src/sys/tests/linter/testValidFunctionDocStrings.c:144:3 Note: Sowing chars declared here: 958 142: PETSC_INTERN PetscErrorCode testInternFunction(); 959 143: 960> 144: /*@ 961 ^ 962 145: testInternFunction - an internal function 963 146: 964 965ERROR 5: ./src/sys/tests/linter/testValidFunctionDocStrings.c:163:23 966'testStaticFunction' of type 'PetscErrorCode ()' (a.k.a. 'int ()') 967 161: .seealso: function() 968 162: @*/ 969> 163: static PetscErrorCode testStaticFunction() 970 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 971 164: { 972 165: return 0; 973 974A sowing docstring for a symbol with internal linkage is pointless [-fdoc-internal-linkage]!: 975 154: } 976 155: 977> 156: /*@ 978> 157: testStaticFunction - an internal function 979> 158: 980> 159: Level: developer 981> 160: 982> 161: .seealso: function() 983> 162: @*/ 984 163: static PetscErrorCode testStaticFunction() 985 164: { 986 987./src/sys/tests/linter/testValidFunctionDocStrings.c:163:1 Note: 'testStaticFunction()' is declared 'STATIC' at ./src/sys/tests/linter/testValidFunctionDocStrings.c:163:23 988'testStaticFunction' of type 'PetscErrorCode ()' (a.k.a. 'int ()') 989 161: .seealso: function() 990 162: @*/ 991> 163: static PetscErrorCode testStaticFunction() 992 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 993 164: { 994 165: return 0; 995 996 997./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. 998 999./src/sys/tests/linter/testValidFunctionDocStrings.c:156:3 Note: Sowing chars declared here: 1000 154: } 1001 155: 1002> 156: /*@ 1003 ^ 1004 157: testStaticFunction - an internal function 1005 158: 1006 1007ERROR 6: ./src/sys/tests/linter/testValidFunctionDocStrings.c:182:16 1008'testAllParamsUndocumented' of type 'PetscErrorCode (PetscInt, PetscInt)' (a.k.a. 'int (int, int)') 1009 180: .seealso: 1010 181: @*/ 1011> 182: PetscErrorCode testAllParamsUndocumented(PetscInt a, PetscInt b) 1012 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1013 183: { 1014 184: return testStaticFunction(); 1015 1016Symbol parameters are all undocumented [-fdoc-param-list-func-parameter-documentation]: 1017 166: } 1018 167: 1019> 168: /*@ 1020> 169: testAllParamsUndocumented - lorem 1021> 170: 1022> 171: Level: beginner developer 1023> 172: 1024> 173: Example Usage: 1025> 174: .vb 1026> 175: int a; 1027> 176: double multiline; 1028> 177: char codeBlock; 1029> 178: .ve 1030> 179: 1031> 180: .seealso: 1032> 181: @*/ 1033 182: PetscErrorCode testAllParamsUndocumented(PetscInt a, PetscInt b) 1034 183: { 1035 1036./src/sys/tests/linter/testValidFunctionDocStrings.c:182:42 Note: Parameters defined here: 1037 180: .seealso: 1038 181: @*/ 1039> 182: PetscErrorCode testAllParamsUndocumented(PetscInt a, PetscInt b) 1040 ^^^^^^^^^^^^^^^^^^^^^^ 1041 183: { 1042 184: return testStaticFunction(); 1043 1044Section appears to be empty; while I'm all for a good mystery, you should probably elaborate here [-fdoc-section-barren]: 1045 178: .ve 1046 179: 1047> 180: .seealso: 1048 ^^^^^^^^^ 1049 181: @*/ 1050 182: PetscErrorCode testAllParamsUndocumented(PetscInt a, PetscInt b) 1051 1052ERROR 7: ./src/sys/tests/linter/testValidFunctionDocStrings.c:199:16 1053'testParameterGrouping' of type 'PetscErrorCode (PetscInt, PetscInt, ...)' (a.k.a. 'int (int, int, ...)') 1054 197: .see also: testStaticFunction() 1055 198: @*/ 1056> 199: PetscErrorCode testParameterGrouping(PetscInt a, PetscInt b, ...) 1057 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1058 200: { 1059 201: return 0; 1060 1061Line seems to be a section header but missing ':', did you mean 'Level:'? [-fdoc-section-header-maybe-header]: 1062 193: . ... - variadic arguments 1063 194: 1064> 195: Level dev 1065 ^^^^^^^^^ 1066 196: 1067 197: .see also: testStaticFunction() 1068 1069Synopsis 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]: 1070 186: 1071 187: /*@ 1072> 188: testParameterGrouping ipsum 1073 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1074 189: 1075 190: Input parameters: 1076 1077Each parameter entry must be documented separately on its own line [-fdoc-param-list-solitary-parameter]: 1078 189: 1079 190: Input parameters: 1080> 191: - a,b - some params 1081 ^^^ 1082 192: + nonExistentParam - this param does not exist 1083 193: . ... - variadic arguments 1084 1085./src/sys/tests/linter/testValidFunctionDocStrings.c:191:3 Note: variable argument lists should be documented in notes 1086 1087Extra docstring parameter 'nonExistentParam' not found in symbol parameter list [-fdoc-param-list-func-parameter-documentation]: 1088 190: Input parameters: 1089 191: - a,b - some params 1090> 192: + nonExistentParam - this param does not exist 1091 ^^^^^^^^^^^^^^^^ 1092 193: . ... - variadic arguments 1093 194: 1094 1095Extra docstring parameter '...' not found in symbol parameter list [-fdoc-param-list-func-parameter-documentation]: 1096 191: - a,b - some params 1097 192: + nonExistentParam - this param does not exist 1098> 193: . ... - variadic arguments 1099 ^^^ 1100 194: 1101 195: Level dev 1102 1103Unknown Level subheading 'dev', expected one of beginner, intermediate, advanced, developer, or deprecated [-fdoc-inline-list-level-spelling]: 1104 193: . ... - variadic arguments 1105 194: 1106> 195: Level dev 1107 ^^^ 1108 196: 1109 197: .see also: testStaticFunction() 1110 1111ERROR 9: ./src/sys/tests/linter/testValidFunctionDocStrings.c:234:16 1112'testBadParamListDescrSep' of type 'PetscErrorCode (PetscInt, PetscInt)' (a.k.a. 'int (int, int)') 1113 232: .seealso: Foo() 1114 233: @*/ 1115> 234: PetscErrorCode testBadParamListDescrSep(PetscInt alpha, PetscInt beta) 1116 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1117 235: { 1118 236: return 0; 1119 1120Parameters 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]: 1121 225: 1122 226: Input Parameters: 1123> 227: + alpha, an alpha 1124 ^^^^^^^^^^^^^^^^^ 1125 228: - beta = a beta 1126 229: 1127 1128Parameters 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]: 1129 226: Input Parameters: 1130 227: + alpha, an alpha 1131> 228: - beta = a beta 1132 ^^^^^^^^^^^^^^^ 1133 229: 1134 230: Level: beginner 1135 1136ERROR 10: ./src/sys/tests/linter/testValidFunctionDocStrings.c:251:16 1137'testBadMidSentenceColons' of type 'PetscErrorCode ()' (a.k.a. 'int ()') 1138 249: .seealso: `Foo() 1139 250: @*/ 1140> 251: PetscErrorCode testBadMidSentenceColons(void) 1141 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1142 252: { 1143 253: return 0; 1144 1145Sowing 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]: 1146 238: 1147 239: /*@ 1148> 240: testBadMidSentenceColons - Lorem: 1149 ^ 1150 241: 1151 242: Notes: 1152 1153Sowing 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]: 1154 243: Lorem ipsum dolor sit amet:, consectetur adipiscing elit: sed do: eiusmod tempor: incididunt ut 1155 244: labore et dolore: magna aliqua: Excepteur: sint occaecat cupidatat non proident, sunt: in culpa 1156> 245: qui officia: deserunt mollit: anim id est: laborum as follows: 1157 ^ 1158 246: 1159 247: Level: beginner 1160 1161ERROR 11: ./src/sys/tests/linter/testValidFunctionDocStrings.c:289:16 1162'testExplicitSynopsis_Private' of type 'PetscErrorCode (PetscScalar, PetscInt, PetscReal, void *)' (a.k.a. 'int (double, int, double, void *)') 1163 287: .seealso: `testExplicitSynopsisBad()` 1164 288: M@*/ 1165> 289: PetscErrorCode testExplicitSynopsis_Private(PetscScalar unknown, PetscInt foo, PetscReal bar, void *baz) 1166 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1167 290: { 1168 291: return 0; 1169 1170Undocumented parameter 'unknown' not found in parameter section [-fdoc-param-list-func-parameter-documentation]: 1171 276: PetscErrorCode testExplicitSynopsis(PetscInt foo, PetscReal bar, void *baz) 1172 277: 1173> 278: Input Parameters: 1174> 279: + foo - a foo 1175> 280: - bar - a bar 1176> 281: 1177> 282: Output Parameter: 1178> 283: . baz - a baz 1179> 284: 1180 285: Level: beginner 1181 286: 1182 1183./src/sys/tests/linter/testValidFunctionDocStrings.c:289:45 Note: Parameter 'unknown' defined here: 1184 288: M@*/ 1185> 289: PetscErrorCode testExplicitSynopsis_Private(PetscScalar unknown, PetscInt foo, PetscReal bar, void *baz) 1186 ^^^^^^^^^^^^^^^^^^^ 1187 290: { 1188 1189ERROR 12: ./src/sys/tests/linter/testValidFunctionDocStrings.c:310:16 1190'testBadDocStringMissingChar' of type 'PetscErrorCode (PetscInt)' (a.k.a. 'int (int)') 1191 308: .seealso: `testBadDocString()` 1192 309: */ 1193> 310: PetscErrorCode testBadDocStringMissingChar(PetscInt n) 1194 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1195 311: { 1196 312: return 0; 1197 1198Docstring missing synopsis [-fdoc-synopsis-missing-description]: 1199 300: 1200 301: /*C testBadDocStringMissingChar - asdadsasd 1201> 302: 1202 303: Input Parameter: 1203 304: . n - the n 1204 1205./src/sys/tests/linter/testValidFunctionDocStrings.c:302:1 Note: Expected 'testBadDocStringMissingChar - a very useful description' 1206 1207ERROR 13: ./src/sys/tests/linter/testValidFunctionDocStrings.c:325:16 1208'testBadDocStringCharOutOfOrder' of type 'PetscErrorCode (PetscInt)' (a.k.a. 'int (int)') 1209 323: .seealso: `testBadDocString()` 1210 324: */ 1211> 325: PetscErrorCode testBadDocStringCharOutOfOrder(PetscInt n) 1212 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1213 326: { 1214 327: return 0; 1215 1216Invalid docstring identifier, contains unexpected char sequence 'C@', expected '/*@C'. Did you put it in the wrong order? [-fdoc-sowing-chars]: 1217 313: } 1218 314: 1219> 315: /*C@ 1220 ^^^^ 1221 316: testBadDocStringCharOutOfOrder - asdadsasd 1222 317: 1223 1224ERROR 15: ./src/sys/tests/linter/testValidFunctionDocStrings.c:381:16 1225'testPredeclarationCursorIgnored' of type 'PetscErrorCode (int, int *)' (a.k.a. 'int (int, int *)') 1226 379: */ 1227 380: 1228> 381: PetscErrorCode testPredeclarationCursorIgnored(int arg, int *another_arg) 1229 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1230 382: { 1231 383: return 0; 1232 1233Invalid comment begin line, does not contain sowing identifier. Expected '/*@' for functions [-fdoc-sowing-chars]: 1234 365: extern PetscErrorCode testPredeclarationCursorIgnored(int, int *); 1235 366: 1236> 367: /* 1237 ^^ 1238 368: testPredeclarationCursorIgnored - the cursor above this will be ignored! 1239 369: 1240 1241Extra docstring parameter 'asdasd' not found in symbol parameter list [-fdoc-param-list-func-parameter-documentation]: 1242 369: 1243 370: Inp Paramet: 1244> 371: . asdasd - an arg 1245 ^^^^^^ 1246 372: 1247 373: Ouput Pameter: 1248 1249Extra docstring parameter 'another_arg_asd22' not found in symbol parameter list [-fdoc-param-list-func-parameter-documentation]: 1250 372: 1251 373: Ouput Pameter: 1252> 374: . another_arg_asd22 - another arg 1253 ^^^^^^^^^^^^^^^^^ 1254 375: 1255 376: Level: beg 1256 1257maybe you meant 'another_arg' of type 'int *' 1258 379: */ 1259 380: 1260> 381: PetscErrorCode testPredeclarationCursorIgnored(int arg, int *another_arg) 1261 ^^^^^^^^^^^^^^^^ 1262 382: { 1263 383: return 0; 1264 1265 1266Undocumented parameter 'arg' not found in parameter section [-fdoc-param-list-func-parameter-documentation]: 1267 368: testPredeclarationCursorIgnored - the cursor above this will be ignored! 1268 369: 1269> 370: Inp Paramet: 1270> 371: . asdasd - an arg 1271> 372: 1272> 373: Ouput Pameter: 1273> 374: . another_arg_asd22 - another arg 1274> 375: 1275 376: Level: beg 1276 377: 1277 1278./src/sys/tests/linter/testValidFunctionDocStrings.c:381:48 Note: Parameter 'arg' defined here: 1279 380: 1280> 381: PetscErrorCode testPredeclarationCursorIgnored(int arg, int *another_arg) 1281 ^^^^^^^ 1282 382: { 1283 1284Unknown Level subheading 'beg', expected one of beginner, intermediate, advanced, developer, or deprecated [-fdoc-inline-list-level-spelling]: 1285 374: . another_arg_asd22 - another arg 1286 375: 1287> 376: Level: beg 1288 ^^^ 1289 377: 1290 378: .seealso: testPredeclarationCursorIgnored()` 1291 1292ERROR 16: ./src/sys/tests/linter/testValidFunctionDocStrings.c:419:16 1293'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))') 1294 417: .seealso: `testPredeclarationCursorIgnored()` 1295 418: */ 1296> 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)) 1297 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1298 420: { 1299 421: return 0; 1300 1301Extra docstring parameter 'foo_parm1' not found in symbol parameter list [-fdoc-param-list-func-parameter-documentation]: 1302 393: 1303 394: Calling sequence of foo: 1304> 395: + foo_parm1 - an int 1305 ^^^^^^^^^ 1306 396: . foo_parm2 - a double 1307 397: - foo_parm3 - a float 1308 1309Extra docstring parameter 'foo_parm2' not found in symbol parameter list [-fdoc-param-list-func-parameter-documentation]: 1310 394: Calling sequence of foo: 1311 395: + foo_parm1 - an int 1312> 396: . foo_parm2 - a double 1313 ^^^^^^^^^ 1314 397: - foo_parm3 - a float 1315 398: 1316 1317Extra docstring parameter 'foo_parm3' not found in symbol parameter list [-fdoc-param-list-func-parameter-documentation]: 1318 395: + foo_parm1 - an int 1319 396: . foo_parm2 - a double 1320> 397: - foo_parm3 - a float 1321 ^^^^^^^^^ 1322 398: 1323 399: Calling sequence of bar: 1324--------------------------------------------------------------------------------------------