Warn on improperly formatted parameter definitions
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 355
- Forks
- 181
- Avg merge
- 1d 9h
- Merged PRs (30d)
- 3
Description
Parameter name and types are split by " : "
val : int
It's a common mistake to leave out the leading space, i.e.
val: int
This results in the whole string being interpreted as "name" and thus incorrect rendering such as:
The relevant code is:
https://github.com/numpy/numpydoc/blob/4dd6fd47cf93112e7b598f3675773adfed013f05/numpydoc/docscrape.py#L229-L239
Would it be desirable to warn in that case? E.g. the most simple check in the else branch could be:
if ": " in header:
# warn
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start in numpydoc/docscrape.py at lines 229-239, where parameter names and types are split. Trace how the else branch handles a header such as val: int, then add a warning for the improperly formatted definition and verify that the warning appears without changing correctly formatted rendering.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 72/100