Provide consistency checks for parameter documentation and links

[rweickelt]

When documenting functions, it can often happen that the documentation does not match the function signature:

/**
 * Function documentation.
 *
 * :param p1: Documentation of p1
 * :param int p22: Documenation of p2 - oops
 * :return: Return value documentation
 * :See also: :c:func:`i_dont_exist`
 */
int foo(int p1, int p2);

It would be nice if Hawkmoth would (on demand)

• ensure consistency and throw a warning in case of a mismatch.
• warn on undocumented parameters and return value
• warn or throw an error when linking to a non-existing symbol (probably not Hawkmoth's business)

I know that some people prefer not to use these directives at all. Thus it would be nice to have that configurable.

[jnikula]

Thanks for the suggestion!

I've thought about this before, but it has always come second to one of the core design principles in Hawkmoth: zero or minimal parsing of the documentation comments.

However, this could be an extension, if the hawkmoth-process-docstring event was also provided with the Clang cursor or similar data. I'll think about this.

@BrunoMSantos we've discussed passing the cursor before. But is it too low level stuff? OTOH, if we provide an abstraction of our own, then that itself may need to be extended.

[jnikula]

warn or throw an error when linking to a non-existing symbol (probably not Hawkmoth's business)

This part I don't think Hawkmoth should do. It's Sphinx stuff.

[BrunoMSantos]

However, this could be an extension, if the hawkmoth-process-docstring event was also provided with the Clang cursor or similar data. I'll think about this.

Well, we had planned to do this even before we had extensions, so I think the feature request stands 😁
But yes, a built in extension seems to fit this nicely provided we extend its API a bit.

@BrunoMSantos we've discussed passing the cursor before. But is it too low level stuff? OTOH, if we provide an abstraction of our own, then that itself may need to be extended.

We did indeed and it's a bit of a pattern... Long overdue, but now we have an issue to point to: #180.

[BrunoMSantos]

warn or throw an error when linking to a non-existing symbol (probably not Hawkmoth's business)

This part I don't think Hawkmoth should do. It's Sphinx stuff.

Agreed. I also believe Sphinx already does this quite well though. Have you tested it?