javadoc: allow space before parameter direction indication

[jnikula]

Having whitespace between @param and [direction] fails to match the param regex:

@param[in] works
@param [in] fails

This is detected but not handled properly, leading to a backtrace about mo.group() being called when mo is None.

Fix the regex and, to an extent, the error handling.

This is just the simplest and quickest fix. There should be better error handling with proper error messages all around, as well as testing.

[BrunoMSantos]

Agree that there should be testing and better error handling, but this is still an improvement and it is a 'side-feature' after all. I think it's fair to merge the regex fix.

[BrunoMSantos]

Can't we suppress the yield then? In fact, why are we using yield in this function at all?

[jnikula]

I guess the design (or lack thereof) is based on this loop:

def _process_docstring(app, lines, transform, options):
    if transform != app.config.hawkmoth_javadoc_transform:
        return

    lines[:] = [line for line in _convert(app=app, lines=lines)]

By having _convert() and anything it calls yield the stuff just works nicely, because the conversion of a single line may result in more than one line.

And rst being rst, it's better to emit the blank line if the conversion fails.

[BrunoMSantos]

Hmm, my brain's fried right now tbh, but we only ever yield once per call of header(), right? Does yielding yield any gain in that case (pun intended)?

[jnikula]

No, header() yields 1-4 lines, depending on the class.

[BrunoMSantos]

Ah, I see, though I don't think it makes a difference if we were to return in the cases where it yields only once. Anyway, the code is correct, and I get the argument of following a pattern 👍