Skip to content
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.

Sign up for GitHub

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

Jump to bottom

Warn on duplicate fields #229

Open
mthuurne opened this issue Oct 21, 2020 · 2 comments
Open

Warn on duplicate fields #229

mthuurne opened this issue Oct 21, 2020 · 2 comments
Labels
good first issue

Comments

@mthuurne
Copy link
Contributor

If for example a return value or a parameter is documented more than once, it would be useful to warn the user about that.

Note that fields such as author, note and seealso can be used multiple times, so not all duplicate fields are a problem.
@mthuurne
Copy link
Contributor Author

mthuurne commented Oct 21, 2020 •
edited
Loading

Duplicate type fields are already warned about, see FieldHandler.redef(). But the warning message itself still uses the old-style full name format, not source location.

Edit: On closer inspection, it turns out that this warning is located in dead code.

@mthuurne mthuurne mentioned this issue Oct 21, 2020
Merged
6 tasks
mthuurne added a commit to boxingbeetle/pydoctor that referenced this issue Oct 22, 2020
@mthuurne
Do not print 'XXX' on duplicate @return or @rtype
a70cac8 
This message is probably a leftover debug message. In any case, it is
not very informational to the user.

It might be useful to warn on duplicate fields for fields where there
is no need to include them multiple times, but that should be done in
a more consistent way. For example, documenting the same parameter more
than once could also be warned about. I created twisted#229 as reminder.
This was referenced Nov 25, 2020
Closed
Merged
mthuurne added a commit to boxingbeetle/pydoctor that referenced this issue Nov 27, 2020
@mthuurne
Warn when a parameter is documented more than once
dc6ca1d 
This is a partial implementation of twisted#229: ideally we'd want to warn on
duplicate `type` and `keyword` fields as well, but for `type` this is
currently not easy to implement and `keyword` isn't used enough to
make it a priority.
mthuurne added a commit to boxingbeetle/pydoctor that referenced this issue Nov 27, 2020
@mthuurne
Warn when a parameter is documented more than once
b9d4e05 
This is a partial implementation of twisted#229: ideally we'd want to warn on
duplicate `type` and `keyword` fields as well, but for `type` this is
currently not easy to implement and `keyword` isn't used enough to
make it a priority.
@mthuurne
Copy link
Contributor Author

mthuurne commented Nov 27, 2020 •
edited
Loading

#296 implements a warning for duplicate param fields. This warning found several issues in Twisted.

It would be good to have a warning for duplicate type fields as well. But the way the self.types dictionary is filled makes this messy to implement, since it is pre-filled with the presentations of the type annotations, so we can't easily detect when a type is defined twice. Another complication is that type fields are not only used for parameters, but also for variables.

The same keyword occurring twice is also something we can warn about, but as keywords aren't used often, so I don't consider this a priority.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
good first issue
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@mthuurne @tristanlatr