<--- FIXED --->
--------------------------------------------------------------------------------------------
ERROR 0: ./src/sys/tests/linter/testValidFunctionDocStrings.c:77:16
'testIllFormedFunctionDocString' of type 'PetscErrorCode (PetscViewer, PetscInt, PetscScalar *, PetscBool)' (a.k.a. 'int (_p_PetscViewer *, int, double *, PetscBool)')
  75: @*/
  76: 
> 77: PetscErrorCode testIllFormedFunctionDocString(PetscViewer viewer, PetscInt x, PetscScalar *y, PetscBool cond)
      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  78: {
  79:   return 0;

Invalid comment begin line, must only contain '/*' and sowing identifier [-fdoc-sowing-chars]:
  32: }
  33: 
> 34: /*@C Lorem ipsum dolor sit amet
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
  35:   someOtherFunctionName - Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
  36:   eiusmod tempor incididunt ut labore et dolore magna aliqua. Excepteur sint occaecat cupidatat

Invalid line-spacing between docstring and the symbol it describes. The docstring must appear immediately above its target [-fdoc-symbol-spacing]:
  74: testIllFormedFunctionDocString(), `testNonExistentFunction()`, testIllFormedMinimalDocString()
  75: @*/
> 76: 
  77: PetscErrorCode testIllFormedFunctionDocString(PetscViewer viewer, PetscInt x, PetscScalar *y, PetscBool cond)
  78: {

Invalid indentation (3), all regular (non-empty, non-parameter, non-seealso) text must be indented to 2 columns [-fdoc-indentation]:
  42:   Not Collective, Synchronous
  43: 
> 44:    Input Parameters:
      ^^^
  45: + viewer - a PetscViewer
  46: 

Solitary parameter list entry must start with '.' [-fdoc-param-list-prefix]:
  43: 
  44:    Input Parameters:
> 45: + viewer - a PetscViewer
      ^
  46: 
  47:   Output Parameter:

First multi parameter list entry must start with '+' [-fdoc-param-list-prefix]:
  46: 
  47:   Output Parameter:
> 48: - y          - a pointer
      ^
  49: + cnd           - a boolean
  50: . z - a nonexistent parameter

Multi parameter list entry must start with '.' [-fdoc-param-list-prefix]:
  47:   Output Parameter:
  48: - y          - a pointer
> 49: + cnd           - a boolean
      ^
  50: . z - a nonexistent parameter
  51: 

Last multi parameter list entry must start with '-' [-fdoc-param-list-prefix]:
  48: - y          - a pointer
  49: + cnd           - a boolean
> 50: . z - a nonexistent parameter
      ^
  51: 
  52:   level: Lorem ipsum dolor sit amet

Description 'a pointer' must be aligned to 1 space from longest (valid) argument 'y' [-fdoc-param-list-alignment]:
  46: 
  47:   Output Parameter:
> 48: - y          - a pointer
          ^^^^^^^^^^^^^^^^^^^^
  49: + cnd           - a boolean
  50: . z - a nonexistent parameter

Extra docstring parameter 'z' not found in symbol parameter list [-fdoc-param-list-func-parameter-documentation]:
  48: - y          - a pointer
  49: + cnd           - a boolean
> 50: . z - a nonexistent parameter
        ^
  51: 
  52:   level: Lorem ipsum dolor sit amet

maybe you meant 'x' of type 'PetscInt' (a.k.a. 'int')
  75: @*/
  76: 
> 77: PetscErrorCode testIllFormedFunctionDocString(PetscViewer viewer, PetscInt x, PetscScalar *y, PetscBool cond)
                                                                        ^^^^^^^^^^
  78: {
  79:   return 0;


Invalid header spelling. Expected 'Level' found 'level' [-fdoc-section-header-spelling]:
  50: . z - a nonexistent parameter
  51: 
> 52:   level: Lorem ipsum dolor sit amet
        ^^^^^
  53: 
  54:   Level:

Level subheading must be lowercase, expected 'beginner' found 'Beginner' [-fdoc-inline-list-level-casefold]:
  53: 
  54: Level:
> 55: Beginner
      ^^^^^^^^
  56: 
  57: Developer Notes:

seealso values must be (1) space away from colon not (50) [-fdoc-inline-list-formatting]:
  71:   References: Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
  72: 
> 73: .seealso:                                                  testNonExistentFunction(), testNonExistentType,
                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  74: testIllFormedFunctionDocString(), `testNonExistentFunction()`, testIllFormedMinimalDocString()
  75: @*/

Found self-referential seealso entry 'testIllFormedFunctionDocString()'; your documentation may be good but it's not *that* good [-fdoc-inline-list-seealso-self-reference]:
  72: 
  73: .seealso:                                                  testNonExistentFunction(), testNonExistentType,
> 74: testIllFormedFunctionDocString(), `testNonExistentFunction()`, testIllFormedMinimalDocString()
      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  75: @*/
  76: 

seealso symbol 'testNonExistentFunction()' not enclosed with '`' [-fdoc-inline-list-seealso-backticks]:
  71:   References: Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
  72: 
> 73: .seealso:                                                  testNonExistentFunction(), testNonExistentType,
                                                                 ^^^^^^^^^^^^^^^^^^^^^^^^^
  74: testIllFormedFunctionDocString(), `testNonExistentFunction()`, testIllFormedMinimalDocString()
  75: @*/

seealso symbol 'testNonExistentType' not enclosed with '`' [-fdoc-inline-list-seealso-backticks]:
  71:   References: Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
  72: 
> 73: .seealso:                                                  testNonExistentFunction(), testNonExistentType,
                                                                                            ^^^^^^^^^^^^^^^^^^^
  74: testIllFormedFunctionDocString(), `testNonExistentFunction()`, testIllFormedMinimalDocString()
  75: @*/

seealso symbol 'testIllFormedMinimalDocString()' not enclosed with '`' [-fdoc-inline-list-seealso-backticks]:
  72: 
  73: .seealso:                                                  testNonExistentFunction(), testNonExistentType,
> 74: testIllFormedFunctionDocString(), `testNonExistentFunction()`, testIllFormedMinimalDocString()
                                                                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  75: @*/
  76: 

ERROR 1: ./src/sys/tests/linter/testValidFunctionDocStrings.c:95:16
'testIllFormedMinimalDocString' of type 'PetscErrorCode ()' (a.k.a. 'int ()')
  93:    .seealso: testNonExistentFunction(), testNonExistentType,`testNonExistentFunction()
  94: */
> 95: PetscErrorCode testIllFormedMinimalDocString(void)
      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  96: {
  97:   return 0;

Invalid indentation (3), all regular (non-empty, non-parameter, non-seealso) text must be indented to 2 columns [-fdoc-indentation]:
  91:   References:
  92:   Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
> 93:    .seealso: testNonExistentFunction(), testNonExistentType,`testNonExistentFunction()
      ^^^
  94: */
  95: PetscErrorCode testIllFormedMinimalDocString(void)

Missing empty line between sections, must have one before this section [-fdoc-section-spacing]:
  91:   References:
  92:   Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
> 93:    .seealso: testNonExistentFunction(), testNonExistentType,`testNonExistentFunction()
  94: */
  95: PetscErrorCode testIllFormedMinimalDocString(void)

Found parameter docstring(s) but 'testIllFormedMinimalDocString()' has no parameters [-fdoc-param-list-func-parameter-documentation]:
  83:   Not Collective, Synchronous
  84: 
> 85:   input parms:
> 86: . foo
> 87: 
> 88:   Output params:
> 89: + bar -
> 90: 
  91:   References:
  92:   Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

seealso symbol 'testNonExistentFunction()' not enclosed with '`' [-fdoc-inline-list-seealso-backticks]:
  91:   References:
  92:   Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
> 93:    .seealso: testNonExistentFunction(), testNonExistentType,`testNonExistentFunction()
                   ^^^^^^^^^^^^^^^^^^^^^^^^^
  94: */
  95: PetscErrorCode testIllFormedMinimalDocString(void)

seealso symbol 'testNonExistentType' not enclosed with '`' [-fdoc-inline-list-seealso-backticks]:
  91:   References:
  92:   Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
> 93:    .seealso: testNonExistentFunction(), testNonExistentType,`testNonExistentFunction()
                                              ^^^^^^^^^^^^^^^^^^^
  94: */
  95: PetscErrorCode testIllFormedMinimalDocString(void)

seealso symbol '`testNonExistentFunction()' not enclosed with '`' [-fdoc-inline-list-seealso-backticks]:
  91:   References:
  92:   Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
> 93:    .seealso: testNonExistentFunction(), testNonExistentType,`testNonExistentFunction()
                                                                  ^^^^^^^^^^^^^^^^^^^^^^^^^^
  94: */
  95: PetscErrorCode testIllFormedMinimalDocString(void)

ERROR 2: ./src/sys/tests/linter/testValidFunctionDocStrings.c:118:16
'testTerribleSpellingDocString' of type 'PetscErrorCode (PetscViewer, PetscInt, PetscScalar *)' (a.k.a. 'int (_p_PetscViewer *, int, double *)')
  116: .zeeakso:
  117: C@*/
> 118: PetscErrorCode testTerribleSpellingDocString(PetscViewer viewer, PetscInt x, PetscScalar *y)
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  119: {
  120:   return 0;

Missing empty line between sections, must have one before this section [-fdoc-section-spacing]:
  112: - -option_a     - foo
  113: - -option_b [filename][:[~]<foo,bar,baz>[:[~]bop]] - descr
> 114:   lvl: itnmediate
  115: 
  116: .zeeakso:

Docstring name 'testTerbleSpelingDocstring' does not match symbol. Assuming you meant 'testTerribleSpellingDocString' [-fdoc-synopsis-matching-symbol-name]:
  99 : 
  100: /*@C
> 101:   testTerbleSpelingDocstring - Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
         ^^^^^^^^^^^^^^^^^^^^^^^^^^
  102:   eiusmod tempor incididunt ut labore et dolore magna aliqua.
  103: 

Unknown section header 'input prametirs', assuming you meant 'Input Parameter' [-fdoc-section-header-spelling]:
  102:   eiusmod tempor incididunt ut labore et dolore magna aliqua.
  103: 
> 104:   input prametirs:
         ^^^^^^^^^^^^^^^
  105: + viewer - a PetsViewer
  106: - x - a PetscInt

Unknown section header 'output Psrammmetrs', assuming you meant 'Output Parameter' [-fdoc-section-header-spelling]:
  106: - x - a PetscInt
  107: 
> 108:   output Psrammmetrs:
         ^^^^^^^^^^^^^^^^^^
  109: . y - a PetscScalar pointer
  110: 

Description 'a PetscInt' must be aligned to 1 space from longest (valid) argument 'viewer' [-fdoc-param-list-alignment]:
  104:   input prametirs:
  105: + viewer - a PetsViewer
> 106: - x - a PetscInt
           ^^^^^^^^^^^^
  107: 
  108:   output Psrammmetrs:

Unknown section header 'optnS dtaaSE', assuming you meant 'Options Database' [-fdoc-section-header-spelling]:
  109: . y - a PetscScalar pointer
  110: 
> 111:   optnS dtaaSE:
         ^^^^^^^^^^^^
  112: - -option_a     - foo
  113: - -option_b [filename][:[~]<foo,bar,baz>[:[~]bop]] - descr

First multi parameter list entry must start with '+' [-fdoc-param-list-prefix]:
  110: 
  111:   optnS dtaaSE:
> 112: - -option_a     - foo
       ^
  113: - -option_b [filename][:[~]<foo,bar,baz>[:[~]bop]] - descr
  114:   lvl: itnmediate

Description 'foo' must be aligned to 1 space from longest (valid) argument '-option_b [filename][:[~]<foo,bar,baz>[:[~]bop]]' [-fdoc-param-list-alignment]:
  110: 
  111:   optnS dtaaSE:
> 112: - -option_a     - foo
                       ^^^^^
  113: - -option_b [filename][:[~]<foo,bar,baz>[:[~]bop]] - descr
  114:   lvl: itnmediate

Unknown section header 'lvl', assuming you meant 'Level' [-fdoc-section-header-spelling]:
  112: - -option_a     - foo
  113: - -option_b [filename][:[~]<foo,bar,baz>[:[~]bop]] - descr
> 114:   lvl: itnmediate
         ^^^
  115: 
  116: .zeeakso:

Unknown Level subheading 'itnmediate', assuming you meant 'intermediate' [-fdoc-inline-list-level-spelling]:
  112: - -option_a     - foo
  113: - -option_b [filename][:[~]<foo,bar,baz>[:[~]bop]] - descr
> 114:   lvl: itnmediate
              ^^^^^^^^^^
  115: 
  116: .zeeakso:

Unknown section header '.zeeakso', assuming you meant '.seealso' [-fdoc-section-header-spelling]:
  114:   lvl: itnmediate
  115: 
> 116: .zeeakso:
       ^^^^^^^^
  117: C@*/
  118: PetscErrorCode testTerribleSpellingDocString(PetscViewer viewer, PetscInt x, PetscScalar *y)

ERROR 3: ./src/sys/tests/linter/testValidFunctionDocStrings.c:134:16
'testCustomFortranInterfaceDocString' of type 'PetscErrorCode (char *******, PetscErrorCode (*)(PetscInt))' (a.k.a. 'int (char *******, int (*)(int))')
  132: .seealso: Lorem(), `ipsum()`, dolor(), `sit(), `amet()`, consectetur(), adipiscing(), elit()`
  133: @*/
> 134: PetscErrorCode testCustomFortranInterfaceDocString(char *******string, PetscErrorCode (*function_ptr)(PetscInt))
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  135: {
  136:   return 0;

Invalid comment begin line, must only contain '/*' and sowing identifier [-fdoc-sowing-chars]:
  121: }
  122: 
> 123: /*@ asdadsadasdas
           ^^^^^^^^^^^^^
  124:   testCustomFortranInterfaceDocString - Lorem ipsum dolor sit amet, consectetur adipiscing elit
  125: 

Function requires custom fortran interface but missing 'C' from docstring header [-fdoc-param-list-func-fortran-interface]:
  121: }
  122: 
> 123: /*@ asdadsadasdas
         ^
  124:   testCustomFortranInterfaceDocString - Lorem ipsum dolor sit amet, consectetur adipiscing elit
  125: 

./src/sys/tests/linter/testValidFunctionDocStrings.c:134:52 Note: due to char pointer 'string' of type 'char *******'
  133: @*/
> 134: PetscErrorCode testCustomFortranInterfaceDocString(char *******string, PetscErrorCode (*function_ptr)(PetscInt))
                                                          ^^^^^^^^^^^^^^^^^^
  135: {

./src/sys/tests/linter/testValidFunctionDocStrings.c:134:72 Note: due to function pointer 'function_ptr' of type 'PetscErrorCode (*)(PetscInt)' (a.k.a. 'int (*)(int)')
  133: @*/
> 134: PetscErrorCode testCustomFortranInterfaceDocString(char *******string, PetscErrorCode (*function_ptr)(PetscInt))
                                                                              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  135: {

Description 'a char pointer' must be aligned to 1 space from longest (valid) argument 'function_ptr' [-fdoc-param-list-alignment]:
  125: 
  126:   Input Parameters:
> 127: + string -  a char pointer
                ^^^^^^^^^^^^^^^^^
  128: - function_ptr - a function pointer
  129: 

seealso symbol 'Lorem()' not enclosed with '`' [-fdoc-inline-list-seealso-backticks]:
  130:   Level:
  131: 
> 132: .seealso: Lorem(), `ipsum()`, dolor(), `sit(), `amet()`, consectetur(), adipiscing(), elit()`
                 ^^^^^^^
  133: @*/
  134: PetscErrorCode testCustomFortranInterfaceDocString(char *******string, PetscErrorCode (*function_ptr)(PetscInt))

seealso symbol 'dolor()' not enclosed with '`' [-fdoc-inline-list-seealso-backticks]:
  130:   Level:
  131: 
> 132: .seealso: Lorem(), `ipsum()`, dolor(), `sit(), `amet()`, consectetur(), adipiscing(), elit()`
                                     ^^^^^^^
  133: @*/
  134: PetscErrorCode testCustomFortranInterfaceDocString(char *******string, PetscErrorCode (*function_ptr)(PetscInt))

seealso symbol '`sit()' not enclosed with '`' [-fdoc-inline-list-seealso-backticks]:
  130:   Level:
  131: 
> 132: .seealso: Lorem(), `ipsum()`, dolor(), `sit(), `amet()`, consectetur(), adipiscing(), elit()`
                                              ^^^^^^
  133: @*/
  134: PetscErrorCode testCustomFortranInterfaceDocString(char *******string, PetscErrorCode (*function_ptr)(PetscInt))

seealso symbol 'consectetur()' not enclosed with '`' [-fdoc-inline-list-seealso-backticks]:
  130:   Level:
  131: 
> 132: .seealso: Lorem(), `ipsum()`, dolor(), `sit(), `amet()`, consectetur(), adipiscing(), elit()`
                                                                ^^^^^^^^^^^^^
  133: @*/
  134: PetscErrorCode testCustomFortranInterfaceDocString(char *******string, PetscErrorCode (*function_ptr)(PetscInt))

seealso symbol 'adipiscing()' not enclosed with '`' [-fdoc-inline-list-seealso-backticks]:
  130:   Level:
  131: 
> 132: .seealso: Lorem(), `ipsum()`, dolor(), `sit(), `amet()`, consectetur(), adipiscing(), elit()`
                                                                               ^^^^^^^^^^^^
  133: @*/
  134: PetscErrorCode testCustomFortranInterfaceDocString(char *******string, PetscErrorCode (*function_ptr)(PetscInt))

seealso symbol 'elit()`' not enclosed with '`' [-fdoc-inline-list-seealso-backticks]:
  130:   Level:
  131: 
> 132: .seealso: Lorem(), `ipsum()`, dolor(), `sit(), `amet()`, consectetur(), adipiscing(), elit()`
                                                                                             ^^^^^^^
  133: @*/
  134: PetscErrorCode testCustomFortranInterfaceDocString(char *******string, PetscErrorCode (*function_ptr)(PetscInt))

ERROR 6: ./src/sys/tests/linter/testValidFunctionDocStrings.c:182:16
'testAllParamsUndocumented' of type 'PetscErrorCode (PetscInt, PetscInt)' (a.k.a. 'int (int, int)')
  180: .seealso:
  181: @*/
> 182: PetscErrorCode testAllParamsUndocumented(PetscInt a, PetscInt b)
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  183: {
  184:   return testStaticFunction();

Unknown Level subheading 'beginner developer', assuming you meant 'developer' [-fdoc-inline-list-level-spelling]:
  169: testAllParamsUndocumented - lorem
  170: 
> 171: Level: beginner developer
              ^^^^^^^^^^^^^^^^^^
  172: 
  173: Example Usage:

ERROR 7: ./src/sys/tests/linter/testValidFunctionDocStrings.c:199:16
'testParameterGrouping' of type 'PetscErrorCode (PetscInt, PetscInt, ...)' (a.k.a. 'int (int, int, ...)')
  197: .see also: testStaticFunction()
  198: @*/
> 199: PetscErrorCode testParameterGrouping(PetscInt a, PetscInt b, ...)
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  200: {
  201:   return 0;

Invalid header spelling. Expected 'Input Parameters' found 'Input parameters' [-fdoc-section-header-spelling]:
  188:   testParameterGrouping ipsum
  189: 
> 190:   Input parameters:
         ^^^^^^^^^^^^^^^^
  191: - a,b - some params
  192: + nonExistentParam - this param does not exist

First multi parameter list entry must start with '+' [-fdoc-param-list-prefix]:
  189: 
  190:   Input parameters:
> 191: - a,b - some params
       ^
  192: + nonExistentParam - this param does not exist
  193: . ... - variadic arguments

Multi parameter list entry must start with '.' [-fdoc-param-list-prefix]:
  190:   Input parameters:
  191: - a,b - some params
> 192: + nonExistentParam - this param does not exist
       ^
  193: . ... - variadic arguments
  194: 

Last multi parameter list entry must start with '-' [-fdoc-param-list-prefix]:
  191: - a,b - some params
  192: + nonExistentParam - this param does not exist
> 193: . ... - variadic arguments
       ^
  194: 
  195:   Level dev

Unknown section header '.see also', assuming you meant '.seealso' [-fdoc-section-header-spelling]:
  195:   Level dev
  196: 
> 197: .see also: testStaticFunction()
       ^^^^^^^^^
  198: @*/
  199: PetscErrorCode testParameterGrouping(PetscInt a, PetscInt b, ...)

seealso symbol 'testStaticFunction()' not enclosed with '`' [-fdoc-inline-list-seealso-backticks]:
  195:   Level dev
  196: 
> 197: .see also: testStaticFunction()
                  ^^^^^^^^^^^^^^^^^^^^
  198: @*/
  199: PetscErrorCode testParameterGrouping(PetscInt a, PetscInt b, ...)

ERROR 8: ./src/sys/tests/linter/testValidFunctionDocStrings.c:218:16
'testScatteredVerbatimBlocks' of type 'PetscErrorCode (PetscInt, PetscInt)' (a.k.a. 'int (int, int)')
  216: .seealso: `Foo()`
  217: @*/
> 218: PetscErrorCode testScatteredVerbatimBlocks(PetscInt alpha, PetscInt beta)
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  219: {
  220:   return 0;

Description 'a beta' must be aligned to 1 space from longest (valid) argument 'alpha' [-fdoc-param-list-alignment]:
  210:   int a_code_block;
  211: .ve
> 212: - beta - a beta
              ^^^^^^^^
  213: 
  214:   Level: beginner

ERROR 9: ./src/sys/tests/linter/testValidFunctionDocStrings.c:234:16
'testBadParamListDescrSep' of type 'PetscErrorCode (PetscInt, PetscInt)' (a.k.a. 'int (int, int)')
  232: .seealso: Foo()
  233: @*/
> 234: PetscErrorCode testBadParamListDescrSep(PetscInt alpha, PetscInt beta)
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  235: {
  236:   return 0;

Description 'an alpha' must be aligned to 1 space from longest (valid) argument 'alpha' [-fdoc-param-list-alignment]:
  225: 
  226:   Input Parameters:
> 227: + alpha, an alpha
              ^^^^^^^^^^
  228: - beta = a beta
  229: 

Description 'a beta' must be aligned to 1 space from longest (valid) argument 'alpha' [-fdoc-param-list-alignment]:
  226:   Input Parameters:
  227: + alpha, an alpha
> 228: - beta = a beta
              ^^^^^^^^
  229: 
  230:   Level: beginner

seealso symbol 'Foo()' not enclosed with '`' [-fdoc-inline-list-seealso-backticks]:
  230:   Level: beginner
  231: 
> 232: .seealso: Foo()
                 ^^^^^
  233: @*/
  234: PetscErrorCode testBadParamListDescrSep(PetscInt alpha, PetscInt beta)

ERROR 10: ./src/sys/tests/linter/testValidFunctionDocStrings.c:251:16
'testBadMidSentenceColons' of type 'PetscErrorCode ()' (a.k.a. 'int ()')
  249: .seealso: `Foo()
  250: @*/
> 251: PetscErrorCode testBadMidSentenceColons(void)
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  252: {
  253:   return 0;

seealso symbol '`Foo()' not enclosed with '`' [-fdoc-inline-list-seealso-backticks]:
  247:   Level: beginner
  248: 
> 249: .seealso: `Foo()
                 ^^^^^^
  250: @*/
  251: PetscErrorCode testBadMidSentenceColons(void)

ERROR 11: ./src/sys/tests/linter/testValidFunctionDocStrings.c:289:16
'testExplicitSynopsis_Private' of type 'PetscErrorCode (PetscScalar, PetscInt, PetscReal, void *)' (a.k.a. 'int (double, int, double, void *)')
  287: .seealso: `testExplicitSynopsisBad()`
  288: M@*/
> 289: PetscErrorCode testExplicitSynopsis_Private(PetscScalar unknown, PetscInt foo, PetscReal bar, void *baz)
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  290: {
  291:   return 0;

Description 'a baz' must be aligned to 1 space from longest (valid) argument 'baz' [-fdoc-param-list-alignment]:
  281: 
  282:   Output Parameter:
> 283: . baz -                 a baz
               ^^^^^^^^^^^^^^^^^^^^^
  284: 
  285:   Level: beginner

ERROR 12: ./src/sys/tests/linter/testValidFunctionDocStrings.c:310:16
'testBadDocStringMissingChar' of type 'PetscErrorCode (PetscInt)' (a.k.a. 'int (int)')
  308: .seealso: `testBadDocString()`
  309: */
> 310: PetscErrorCode testBadDocStringMissingChar(PetscInt n)
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  311: {
  312:   return 0;

Invalid docstring identifier, contains unexpected char sequence 'C', expected '/*@C'. It appears you forgot to prepend '@'? [-fdoc-sowing-chars]:
  299: }
  300: 
> 301: /*C testBadDocStringMissingChar - asdadsasd
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  302: 
  303:   Input Parameter:

Invalid comment begin line, must only contain '/*' and sowing identifier [-fdoc-sowing-chars]:
  299: }
  300: 
> 301: /*C testBadDocStringMissingChar - asdadsasd
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  302: 
  303:   Input Parameter:

ERROR 14: ./src/sys/tests/linter/testValidFunctionDocStrings.c:360:16
'testSingleFunctionArgNotFound' of type 'PetscErrorCode (PetscScalar)' (a.k.a. 'int (double)')
  358: 
  359: @*/
> 360: PetscErrorCode testSingleFunctionArgNotFound(PetscScalar some_function_arg)
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  361: {
  362:   return 0;

Unknown section header 'Input parm', assuming you meant 'Input Parameter' [-fdoc-section-header-spelling]:
  350:   testSingleFunctionArgNotFound - asdasdasdasd
  351: 
> 352:   Input parm:
         ^^^^^^^^^^
  353: + unrelated - A function arg
  354: 

Solitary parameter list entry must start with '.' [-fdoc-param-list-prefix]:
  351: 
  352:   Input parm:
> 353: + unrelated - A function arg
       ^
  354: 
  355:   lvel: dev

Extra docstring parameter 'unrelated' not found in symbol parameter list [-fdoc-param-list-func-parameter-documentation]:
  351: 
  352:   Input parm:
> 353: + unrelated - A function arg
         ^^^^^^^^^
  354: 
  355:   lvel: dev

maybe you meant 'some_function_arg' of type 'PetscScalar' (a.k.a. 'double')
  358: 
  359: @*/
> 360: PetscErrorCode testSingleFunctionArgNotFound(PetscScalar some_function_arg)
                                                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  361: {
  362:   return 0;


Unknown section header 'lvel', assuming you meant 'Level' [-fdoc-section-header-spelling]:
  353: + unrelated - A function arg
  354: 
> 355:   lvel: dev
         ^^^^
  356: 
  357: .seealso: `testBadDocString()

seealso symbol '`testBadDocString()' not enclosed with '`' [-fdoc-inline-list-seealso-backticks]:
  355:   lvel: dev
  356: 
> 357: .seealso: `testBadDocString()
                 ^^^^^^^^^^^^^^^^^^^
  358: 
  359: @*/

ERROR 15: ./src/sys/tests/linter/testValidFunctionDocStrings.c:381:16
'testPredeclarationCursorIgnored' of type 'PetscErrorCode (int, int *)' (a.k.a. 'int (int, int *)')
  379: */
  380: 
> 381: PetscErrorCode testPredeclarationCursorIgnored(int arg, int *another_arg)
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  382: {
  383:   return 0;

Invalid line-spacing between docstring and the symbol it describes. The docstring must appear immediately above its target [-fdoc-symbol-spacing]:
  378: .seealso: testPredeclarationCursorIgnored()`
  379: */
> 380: 
  381: PetscErrorCode testPredeclarationCursorIgnored(int arg, int *another_arg)
  382: {

Unknown section header 'Inp Paramet', assuming you meant 'Input Parameter' [-fdoc-section-header-spelling]:
  368:   testPredeclarationCursorIgnored - the cursor above this will be ignored!
  369: 
> 370:   Inp Paramet:
         ^^^^^^^^^^^
  371: . asdasd - an arg
  372: 

Unknown section header 'Ouput Pameter', assuming you meant 'Output Parameter' [-fdoc-section-header-spelling]:
  371: . asdasd - an arg
  372: 
> 373:   Ouput Pameter:
         ^^^^^^^^^^^^^
  374: . another_arg_asd22 - another arg
  375: 

seealso symbol 'testPredeclarationCursorIgnored()`' not enclosed with '`' [-fdoc-inline-list-seealso-backticks]:
  376:   Level: beg
  377: 
> 378: .seealso: testPredeclarationCursorIgnored()`
                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  379: */
  380: 

ERROR 16: ./src/sys/tests/linter/testValidFunctionDocStrings.c:419:16
'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))')
  417: .seealso: `testPredeclarationCursorIgnored()`
  418: */
> 419: PetscErrorCode testFunctionPointerArguments(int (*foo)(int, double, float), int (*bar)(int bar_parm1, double bar_parm2, float bar_parm3), void (*baz)(int (*bop)(void), void (*blitz)(void (*)(void)), int baz_parm1, double baz_parm2, float baz_parm3))
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  420: {
  421:   return 0;

Function requires custom fortran interface but missing 'C' from docstring header [-fdoc-param-list-func-fortran-interface]:
  384: }
  385: 
> 386: /*@
         ^
  387:   testFunctionPointerArguments - the first set of arguments are unnamed and should be errored
  388: 

./src/sys/tests/linter/testValidFunctionDocStrings.c:419:45 Note: due to function pointer 'foo' of type 'int (*)(int, double, float)'
  418: */
> 419: PetscErrorCode testFunctionPointerArguments(int (*foo)(int, double, float), int (*bar)(int bar_parm1, double bar_parm2, float bar_parm3), void (*baz)(int (*bop)(void), void (*blitz)(void (*)(void)), int baz_parm1, double baz_parm2, float baz_parm3))
                                                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  420: {

./src/sys/tests/linter/testValidFunctionDocStrings.c:419:77 Note: due to function pointer 'bar' of type 'int (*)(int, double, float)'
  418: */
> 419: PetscErrorCode testFunctionPointerArguments(int (*foo)(int, double, float), int (*bar)(int bar_parm1, double bar_parm2, float bar_parm3), void (*baz)(int (*bop)(void), void (*blitz)(void (*)(void)), int baz_parm1, double baz_parm2, float baz_parm3))
                                                                                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  420: {

./src/sys/tests/linter/testValidFunctionDocStrings.c:419:139 Note: due to function pointer 'baz' of type 'void (*)(int (*)(), void (*)(void (*)()), int, double, float)'
  418: */
> 419: PetscErrorCode testFunctionPointerArguments(int (*foo)(int, double, float), int (*bar)(int bar_parm1, double bar_parm2, float bar_parm3), void (*baz)(int (*bop)(void), void (*blitz)(void (*)(void)), int baz_parm1, double baz_parm2, float baz_parm3))
                                                                                                                                                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  420: {

ERROR 17: ./src/sys/tests/linter/testValidFunctionDocStrings.c:448:16
'testIllFormedDeprecated' of type 'PetscErrorCode ()' (a.k.a. 'int ()')
  446: .seealso: `testDeprecated()`
  447: */
> 448: PetscErrorCode testIllFormedDeprecated(void)
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  449: {
  450:   return PETSC_SUCCESS;

Found parameter docstring(s) but 'testIllFormedDeprecated()' has no parameters [-fdoc-param-list-func-parameter-documentation]:
  437:   testIllFormedDeprecated - check that deprecated (since VERSION) works
  438: 
> 439:   Input Parameters:
> 440: + foo - a nonexistent foo
> 441: . bar - a nonexistent bar
> 442: - baz - a nonexistent baz
> 443: 
  444:   Level: dpcrtd (since 3.18.5)
  445: 

Unknown Level subheading 'dpcrtd', assuming you meant 'deprecated' [-fdoc-inline-list-level-spelling]:
  442: - baz - a nonexistent baz
  443: 
> 444:   Level: dpcrtd (since 3.18.5)
                ^^^^^^
  445: 
  446: .seealso: `testDeprecated()`
--------------------------------------------------------------------------------------------
<--- LEFT --->
--------------------------------------------------------------------------------------------
ERROR 0: ./src/sys/tests/linter/testValidFunctionDocStrings.c:77:16
'testIllFormedFunctionDocString' of type 'PetscErrorCode (PetscViewer, PetscInt, PetscScalar *, PetscBool)' (a.k.a. 'int (_p_PetscViewer *, int, double *, PetscBool)')
  75: @*/
  76: 
> 77: PetscErrorCode testIllFormedFunctionDocString(PetscViewer viewer, PetscInt x, PetscScalar *y, PetscBool cond)
      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  78: {
  79:   return 0;

Sowing 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]:
  58: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut
  59: labore et dolore magna aliqua. Excepteur sint occaecat cupidatat non proident, sunt in culpa
> 60: qui officia deserunt mollit anim id est laborum as follows:
                                                                ^
  61: 
  62: Notes Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor

Line seems to be a section header but missing ':', did you mean 'Notes:'? [-fdoc-section-header-maybe-header]:
  60: qui officia deserunt mollit anim id est laborum as follows:
  61: 
> 62: Notes Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
      ^^^^^
  63: incididunt ut labore et dolore magna aliqua. Excepteur sint occaecat cupidatat non proident,
  64: sunt in culpa qui officia deserunt mollit anim id est laborum example.

Sowing 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]:
  67: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut
  68: labore et dolore magna aliqua. Excepteur sint occaecat cupidatat non proident, sunt in culpa
> 69: qui officia deserunt mollit anim id est laborum instance:
                                                              ^
  70: 
  71: References: Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Docstring name 'someOtherFunctionName' does not match symbol name 'testIllFormedFunctionDocString' [-fdoc-synopsis-matching-symbol-name]:
  33: 
  34: /*@C Lorem ipsum dolor sit amet
> 35:   someOtherFunctionName - Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
        ^^^^^^^^^^^^^^^^^^^^^
  36:   eiusmod tempor incididunt ut labore et dolore magna aliqua. Excepteur sint occaecat cupidatat
  37:   non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Sed ut

Synopsis 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]:
  33: 
  34: /*@C Lorem ipsum dolor sit amet
> 35:   someOtherFunctionName - Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
> 36:   eiusmod tempor incididunt ut labore et dolore magna aliqua. Excepteur sint occaecat cupidatat
> 37:   non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Sed ut
> 38:   perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium,
> 39:   totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae
> 40:   vitae dicta sunt explicabo.
> 41: 
> 42:   Not Collective, Synchronous
> 43: 
  44:    Input Parameters:
  45: + viewer - a PetscViewer

Extra docstring parameter 'cnd' not found in symbol parameter list [-fdoc-param-list-func-parameter-documentation]:
  47:   Output Parameter:
  48: - y          - a pointer
> 49: + cnd           - a boolean
        ^^^
  50: . z - a nonexistent parameter
  51: 

maybe you meant 'cond' of type 'PetscBool'
  75: @*/
  76: 
> 77: PetscErrorCode testIllFormedFunctionDocString(PetscViewer viewer, PetscInt x, PetscScalar *y, PetscBool cond)
                                                                                                    ^^^^^^^^^^^^^^
  78: {
  79:   return 0;


Heading must appear alone on a line, any content must be on the next line [-fdoc-section-header-solitary]:
  60: qui officia deserunt mollit anim id est laborum as follows:
  61: 
> 62: Notes Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  63: incididunt ut labore et dolore magna aliqua. Excepteur sint occaecat cupidatat non proident,
  64: sunt in culpa qui officia deserunt mollit anim id est laborum example.

Multiple 'Level' subheadings. Much like Highlanders, there can only be one [-fdoc-section-header-unique]:
  50: . z - a nonexistent parameter
  51: 
> 52:   level: Lorem ipsum dolor sit amet
        ^^^^^
  53: 
> 54:   Level:
        ^^^^^
  55:   Beginner
  56: 

Unknown Level subheading 'Lorem ipsum dolor sit amet', expected one of beginner, intermediate, advanced, developer, or deprecated [-fdoc-inline-list-level-spelling]:
  50: . z - a nonexistent parameter
  51: 
> 52:   level: Lorem ipsum dolor sit amet
               ^^^^^
  53: 
  54:   Level:

ERROR 1: ./src/sys/tests/linter/testValidFunctionDocStrings.c:95:16
'testIllFormedMinimalDocString' of type 'PetscErrorCode ()' (a.k.a. 'int ()')
  93:    .seealso: testNonExistentFunction(), testNonExistentType,`testNonExistentFunction()
  94: */
> 95: PetscErrorCode testIllFormedMinimalDocString(void)
      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  96: {
  97:   return 0;

Invalid comment begin line, does not contain sowing identifier. Expected '/*@' for functions [-fdoc-sowing-chars]:
  80: }
  81: 
> 82: /*
      ^^
  83:   Not Collective, Synchronous
  84: 

Docstring missing synopsis [-fdoc-synopsis-missing-description]:
  81: 
  82: /*
> 83:   Not Collective, Synchronous
> 84: 
  85:   input parms:
  86: . foo

./src/sys/tests/linter/testValidFunctionDocStrings.c:83:1 Note: Expected 'testIllFormedMinimalDocString - a very useful description'

Required section 'Level' not found [-fdoc-section-header-missing]:
  80: }
  81: 
> 82: /*
> 83:   Not Collective, Synchronous
> 84: 
> 85:   input parms:
> 86: . foo
> 87: 
> 88:   Output params:
> 89: + bar -
> 90: 
> 91:   References:
> 92:   Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
> 93:    .seealso: testNonExistentFunction(), testNonExistentType,`testNonExistentFunction()
> 94: */
  95: PetscErrorCode testIllFormedMinimalDocString(void)
  96: {

ERROR 2: ./src/sys/tests/linter/testValidFunctionDocStrings.c:118:16
'testTerribleSpellingDocString' of type 'PetscErrorCode (PetscViewer, PetscInt, PetscScalar *)' (a.k.a. 'int (_p_PetscViewer *, int, double *)')
  116: .zeeakso:
  117: C@*/
> 118: PetscErrorCode testTerribleSpellingDocString(PetscViewer viewer, PetscInt x, PetscScalar *y)
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  119: {
  120:   return 0;

Section appears to be empty; while I'm all for a good mystery, you should probably elaborate here [-fdoc-section-barren]:
  114:   lvl: itnmediate
  115: 
> 116: .zeeakso:
       ^^^^^^^^^
  117: C@*/
  118: PetscErrorCode testTerribleSpellingDocString(PetscViewer viewer, PetscInt x, PetscScalar *y)

ERROR 3: ./src/sys/tests/linter/testValidFunctionDocStrings.c:134:16
'testCustomFortranInterfaceDocString' of type 'PetscErrorCode (char *******, PetscErrorCode (*)(PetscInt))' (a.k.a. 'int (char *******, int (*)(int))')
  132: .seealso: Lorem(), `ipsum()`, dolor(), `sit(), `amet()`, consectetur(), adipiscing(), elit()`
  133: @*/
> 134: PetscErrorCode testCustomFortranInterfaceDocString(char *******string, PetscErrorCode (*function_ptr)(PetscInt))
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  135: {
  136:   return 0;

Section appears to be empty; while I'm all for a good mystery, you should probably elaborate here [-fdoc-section-barren]:
  128: - function_ptr - a function pointer
  129: 
> 130:   Level:
> 131: 
  132: .seealso: Lorem(), `ipsum()`, dolor(), `sit(), `amet()`, consectetur(), adipiscing(), elit()`
  133: @*/

ERROR 4: ./src/sys/tests/linter/testValidFunctionDocStrings.c:151:16
'testInternFunction' of type 'PetscErrorCode ()' (a.k.a. 'int ()')
  149: .seealso: function()
  150: @*/
> 151: PetscErrorCode testInternFunction()
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  152: {
  153:   return 0;

A sowing docstring for a symbol with internal linkage is pointless [-fdoc-internal-linkage]!:
  142: PETSC_INTERN PetscErrorCode testInternFunction();
  143: 
> 144: /*@
> 145:   testInternFunction - an internal function
> 146: 
> 147:   Level: developer
> 148: 
> 149: .seealso: function()
> 150: @*/
  151: PetscErrorCode testInternFunction()
  152: {

./src/sys/tests/linter/testValidFunctionDocStrings.c:142:1 Note: 'testInternFunction()' is declared 'PETSC_INTERN' at ./src/sys/tests/linter/testValidFunctionDocStrings.c:142:1
'hidden' of type ''
  140: void function() { }
  141: 
> 142: PETSC_INTERN PetscErrorCode testInternFunction();
       ^^^^^^^^^^^^
  143: 
  144: /*@


./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.

./src/sys/tests/linter/testValidFunctionDocStrings.c:144:3 Note: Sowing chars declared here:
  142: PETSC_INTERN PetscErrorCode testInternFunction();
  143: 
> 144: /*@
         ^
  145:   testInternFunction - an internal function
  146: 

ERROR 5: ./src/sys/tests/linter/testValidFunctionDocStrings.c:163:23
'testStaticFunction' of type 'PetscErrorCode ()' (a.k.a. 'int ()')
  161: .seealso: function()
  162: @*/
> 163: static PetscErrorCode testStaticFunction()
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  164: {
  165:   return 0;

A sowing docstring for a symbol with internal linkage is pointless [-fdoc-internal-linkage]!:
  154: }
  155: 
> 156: /*@
> 157:   testStaticFunction - an internal function
> 158: 
> 159:   Level: developer
> 160: 
> 161: .seealso: function()
> 162: @*/
  163: static PetscErrorCode testStaticFunction()
  164: {

./src/sys/tests/linter/testValidFunctionDocStrings.c:163:1 Note: 'testStaticFunction()' is declared 'STATIC' at ./src/sys/tests/linter/testValidFunctionDocStrings.c:163:23
'testStaticFunction' of type 'PetscErrorCode ()' (a.k.a. 'int ()')
  161: .seealso: function()
  162: @*/
> 163: static PetscErrorCode testStaticFunction()
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  164: {
  165:   return 0;


./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.

./src/sys/tests/linter/testValidFunctionDocStrings.c:156:3 Note: Sowing chars declared here:
  154: }
  155: 
> 156: /*@
         ^
  157:   testStaticFunction - an internal function
  158: 

ERROR 6: ./src/sys/tests/linter/testValidFunctionDocStrings.c:182:16
'testAllParamsUndocumented' of type 'PetscErrorCode (PetscInt, PetscInt)' (a.k.a. 'int (int, int)')
  180: .seealso:
  181: @*/
> 182: PetscErrorCode testAllParamsUndocumented(PetscInt a, PetscInt b)
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  183: {
  184:   return testStaticFunction();

Symbol parameters are all undocumented [-fdoc-param-list-func-parameter-documentation]:
  166: }
  167: 
> 168: /*@
> 169:   testAllParamsUndocumented - lorem
> 170: 
> 171:   Level: beginner developer
> 172: 
> 173:   Example Usage:
> 174: .vb
> 175:   int a;
> 176:   double multiline;
> 177:   char codeBlock;
> 178: .ve
> 179: 
> 180: .seealso:
> 181: @*/
  182: PetscErrorCode testAllParamsUndocumented(PetscInt a, PetscInt b)
  183: {

./src/sys/tests/linter/testValidFunctionDocStrings.c:182:42 Note: Parameters defined here:
  180: .seealso:
  181: @*/
> 182: PetscErrorCode testAllParamsUndocumented(PetscInt a, PetscInt b)
                                                ^^^^^^^^^^^^^^^^^^^^^^
  183: {
  184:   return testStaticFunction();

Section appears to be empty; while I'm all for a good mystery, you should probably elaborate here [-fdoc-section-barren]:
  178: .ve
  179: 
> 180: .seealso:
       ^^^^^^^^^
  181: @*/
  182: PetscErrorCode testAllParamsUndocumented(PetscInt a, PetscInt b)

ERROR 7: ./src/sys/tests/linter/testValidFunctionDocStrings.c:199:16
'testParameterGrouping' of type 'PetscErrorCode (PetscInt, PetscInt, ...)' (a.k.a. 'int (int, int, ...)')
  197: .see also: testStaticFunction()
  198: @*/
> 199: PetscErrorCode testParameterGrouping(PetscInt a, PetscInt b, ...)
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  200: {
  201:   return 0;

Line seems to be a section header but missing ':', did you mean 'Level:'? [-fdoc-section-header-maybe-header]:
  193: . ... - variadic arguments
  194: 
> 195:   Level dev
         ^^^^^^^^^
  196: 
  197: .see also: testStaticFunction()

Synopsis 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]:
  186: 
  187: /*@
> 188:   testParameterGrouping ipsum
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  189: 
  190:   Input parameters:

Each parameter entry must be documented separately on its own line [-fdoc-param-list-solitary-parameter]:
  189: 
  190:   Input parameters:
> 191: - a,b - some params
         ^^^
  192: + nonExistentParam - this param does not exist
  193: . ... - variadic arguments

./src/sys/tests/linter/testValidFunctionDocStrings.c:191:3 Note: variable argument lists should be documented in notes

Extra docstring parameter 'nonExistentParam' not found in symbol parameter list [-fdoc-param-list-func-parameter-documentation]:
  190:   Input parameters:
  191: - a,b - some params
> 192: + nonExistentParam - this param does not exist
         ^^^^^^^^^^^^^^^^
  193: . ... - variadic arguments
  194: 

Extra docstring parameter '...' not found in symbol parameter list [-fdoc-param-list-func-parameter-documentation]:
  191: - a,b - some params
  192: + nonExistentParam - this param does not exist
> 193: . ... - variadic arguments
         ^^^
  194: 
  195:   Level dev

Unknown Level subheading 'dev', expected one of beginner, intermediate, advanced, developer, or deprecated [-fdoc-inline-list-level-spelling]:
  193: . ... - variadic arguments
  194: 
> 195:   Level dev
               ^^^
  196: 
  197: .see also: testStaticFunction()

ERROR 9: ./src/sys/tests/linter/testValidFunctionDocStrings.c:234:16
'testBadParamListDescrSep' of type 'PetscErrorCode (PetscInt, PetscInt)' (a.k.a. 'int (int, int)')
  232: .seealso: Foo()
  233: @*/
> 234: PetscErrorCode testBadParamListDescrSep(PetscInt alpha, PetscInt beta)
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  235: {
  236:   return 0;

Parameters 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]:
  225: 
  226:   Input Parameters:
> 227: + alpha, an alpha
       ^^^^^^^^^^^^^^^^^
  228: - beta = a beta
  229: 

Parameters 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]:
  226:   Input Parameters:
  227: + alpha, an alpha
> 228: - beta = a beta
       ^^^^^^^^^^^^^^^
  229: 
  230:   Level: beginner

ERROR 10: ./src/sys/tests/linter/testValidFunctionDocStrings.c:251:16
'testBadMidSentenceColons' of type 'PetscErrorCode ()' (a.k.a. 'int ()')
  249: .seealso: `Foo()
  250: @*/
> 251: PetscErrorCode testBadMidSentenceColons(void)
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  252: {
  253:   return 0;

Sowing 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]:
  238: 
  239: /*@
> 240:   testBadMidSentenceColons - Lorem:
                                         ^
  241: 
  242:   Notes:

Sowing 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]:
  243: Lorem ipsum dolor sit amet:, consectetur adipiscing elit: sed do: eiusmod tempor: incididunt ut
  244: labore et dolore: magna aliqua: Excepteur: sint occaecat cupidatat non proident, sunt: in culpa
> 245: qui officia: deserunt mollit: anim id est: laborum as follows:
                                                                    ^
  246: 
  247: Level: beginner

ERROR 11: ./src/sys/tests/linter/testValidFunctionDocStrings.c:289:16
'testExplicitSynopsis_Private' of type 'PetscErrorCode (PetscScalar, PetscInt, PetscReal, void *)' (a.k.a. 'int (double, int, double, void *)')
  287: .seealso: `testExplicitSynopsisBad()`
  288: M@*/
> 289: PetscErrorCode testExplicitSynopsis_Private(PetscScalar unknown, PetscInt foo, PetscReal bar, void *baz)
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  290: {
  291:   return 0;

Undocumented parameter 'unknown' not found in parameter section [-fdoc-param-list-func-parameter-documentation]:
  276:   PetscErrorCode testExplicitSynopsis(PetscInt foo, PetscReal bar, void *baz)
  277: 
> 278:   Input Parameters:
> 279: + foo - a foo
> 280: - bar - a bar
> 281: 
> 282:   Output Parameter:
> 283: . baz -                 a baz
> 284: 
  285:   Level: beginner
  286: 

./src/sys/tests/linter/testValidFunctionDocStrings.c:289:45 Note: Parameter 'unknown' defined here:
  288: M@*/
> 289: PetscErrorCode testExplicitSynopsis_Private(PetscScalar unknown, PetscInt foo, PetscReal bar, void *baz)
                                                   ^^^^^^^^^^^^^^^^^^^
  290: {

ERROR 12: ./src/sys/tests/linter/testValidFunctionDocStrings.c:310:16
'testBadDocStringMissingChar' of type 'PetscErrorCode (PetscInt)' (a.k.a. 'int (int)')
  308: .seealso: `testBadDocString()`
  309: */
> 310: PetscErrorCode testBadDocStringMissingChar(PetscInt n)
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  311: {
  312:   return 0;

Docstring missing synopsis [-fdoc-synopsis-missing-description]:
  300: 
  301: /*C testBadDocStringMissingChar - asdadsasd
> 302: 
  303:   Input Parameter:
  304: . n - the n

./src/sys/tests/linter/testValidFunctionDocStrings.c:302:1 Note: Expected 'testBadDocStringMissingChar - a very useful description'

ERROR 13: ./src/sys/tests/linter/testValidFunctionDocStrings.c:325:16
'testBadDocStringCharOutOfOrder' of type 'PetscErrorCode (PetscInt)' (a.k.a. 'int (int)')
  323: .seealso: `testBadDocString()`
  324: */
> 325: PetscErrorCode testBadDocStringCharOutOfOrder(PetscInt n)
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  326: {
  327:   return 0;

Invalid docstring identifier, contains unexpected char sequence 'C@', expected '/*@C'. Did you put it in the wrong order? [-fdoc-sowing-chars]:
  313: }
  314: 
> 315: /*C@
       ^^^^
  316:   testBadDocStringCharOutOfOrder - asdadsasd
  317: 

ERROR 15: ./src/sys/tests/linter/testValidFunctionDocStrings.c:381:16
'testPredeclarationCursorIgnored' of type 'PetscErrorCode (int, int *)' (a.k.a. 'int (int, int *)')
  379: */
  380: 
> 381: PetscErrorCode testPredeclarationCursorIgnored(int arg, int *another_arg)
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  382: {
  383:   return 0;

Invalid comment begin line, does not contain sowing identifier. Expected '/*@' for functions [-fdoc-sowing-chars]:
  365: extern PetscErrorCode testPredeclarationCursorIgnored(int, int *);
  366: 
> 367: /*
       ^^
  368:   testPredeclarationCursorIgnored - the cursor above this will be ignored!
  369: 

Extra docstring parameter 'asdasd' not found in symbol parameter list [-fdoc-param-list-func-parameter-documentation]:
  369: 
  370:   Inp Paramet:
> 371: . asdasd - an arg
         ^^^^^^
  372: 
  373:   Ouput Pameter:

Extra docstring parameter 'another_arg_asd22' not found in symbol parameter list [-fdoc-param-list-func-parameter-documentation]:
  372: 
  373:   Ouput Pameter:
> 374: . another_arg_asd22 - another arg
         ^^^^^^^^^^^^^^^^^
  375: 
  376:   Level: beg

maybe you meant 'another_arg' of type 'int *'
  379: */
  380: 
> 381: PetscErrorCode testPredeclarationCursorIgnored(int arg, int *another_arg)
                                                               ^^^^^^^^^^^^^^^^
  382: {
  383:   return 0;


Undocumented parameter 'arg' not found in parameter section [-fdoc-param-list-func-parameter-documentation]:
  368:   testPredeclarationCursorIgnored - the cursor above this will be ignored!
  369: 
> 370:   Inp Paramet:
> 371: . asdasd - an arg
> 372: 
> 373:   Ouput Pameter:
> 374: . another_arg_asd22 - another arg
> 375: 
  376:   Level: beg
  377: 

./src/sys/tests/linter/testValidFunctionDocStrings.c:381:48 Note: Parameter 'arg' defined here:
  380: 
> 381: PetscErrorCode testPredeclarationCursorIgnored(int arg, int *another_arg)
                                                      ^^^^^^^
  382: {

Unknown Level subheading 'beg', expected one of beginner, intermediate, advanced, developer, or deprecated [-fdoc-inline-list-level-spelling]:
  374: . another_arg_asd22 - another arg
  375: 
> 376:   Level: beg
                ^^^
  377: 
  378: .seealso: testPredeclarationCursorIgnored()`

ERROR 16: ./src/sys/tests/linter/testValidFunctionDocStrings.c:419:16
'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))')
  417: .seealso: `testPredeclarationCursorIgnored()`
  418: */
> 419: PetscErrorCode testFunctionPointerArguments(int (*foo)(int, double, float), int (*bar)(int bar_parm1, double bar_parm2, float bar_parm3), void (*baz)(int (*bop)(void), void (*blitz)(void (*)(void)), int baz_parm1, double baz_parm2, float baz_parm3))
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  420: {
  421:   return 0;

Extra docstring parameter 'foo_parm1' not found in symbol parameter list [-fdoc-param-list-func-parameter-documentation]:
  393: 
  394:   Calling sequence of foo:
> 395: + foo_parm1 - an int
         ^^^^^^^^^
  396: . foo_parm2 - a double
  397: - foo_parm3 - a float

Extra docstring parameter 'foo_parm2' not found in symbol parameter list [-fdoc-param-list-func-parameter-documentation]:
  394:   Calling sequence of foo:
  395: + foo_parm1 - an int
> 396: . foo_parm2 - a double
         ^^^^^^^^^
  397: - foo_parm3 - a float
  398: 

Extra docstring parameter 'foo_parm3' not found in symbol parameter list [-fdoc-param-list-func-parameter-documentation]:
  395: + foo_parm1 - an int
  396: . foo_parm2 - a double
> 397: - foo_parm3 - a float
         ^^^^^^^^^
  398: 
  399:   Calling sequence of bar:
--------------------------------------------------------------------------------------------