feat: Enhance parameter parsing to handle invalid type info and add related tests #396
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR enhances the parsing of
:param xxxx yyyy:
tags in the sphinx style docstrings, when the type in the middle is invalid because of added spaces (not single word).According to these sphinx docs, the types and parameters can be combined only when there are no spaces in the type:
When there are spaces, there are more than 3 elements in the
directive_parts
of theparsed_directive
. Before this PR, the whole parameter would be skipped (optionally showing warnings) and just not shown in the rendered docs, and it is quite unexpected, as there was some valid description text added. Apart from the type information, there isn't any problem in parsing the directive, if the last part (last element of the list) is the parameter and isn't duplicated and is part of the signature. These two checks are already made below.What this PR does, is to simply ignore the wrong type information (still outputting a warning), but at least keep the parameter name and the text added, so it isn't discarded completely. I consider the typing information as a supplement in the documentation of a function, but missing a parameter completely is far worse.