Skip to content

feat: Enhance parameter parsing to handle invalid type info and add related tests #396

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 14, 2025

Conversation

echoix
Copy link
Contributor

@echoix echoix commented Jul 13, 2025

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:

It is also possible to combine parameter type and description, if the type is a single word, like this:

:param int priority: The priority of the message, can be a number 1-5

When there are spaces, there are more than 3 elements in the directive_parts of the parsed_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.

Copy link
Member

@pawamoy pawamoy left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey @echoix, looking good, thanks a lot!

@pawamoy pawamoy merged commit cbce5a2 into mkdocstrings:main Jul 14, 2025
24 of 26 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants