-
Notifications
You must be signed in to change notification settings - Fork 15
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
[google] Adding types to the documentation should not be enforced #19
Comments
Interesting. I wasn't quite familiar with the Google docstring style before. So if we use the Google style, we should either have type hints in the signature, or in the docstring, but never both. Is my understanding correct? I can already think of edge cases where people intentionally or unintentionally abuse this guide: def myFunc(arg1, arg2: int, arg3: str) -> bool:
"""
Do something
Args:
arg1 (str): Arg 1
arg2: Arg 2
arg3: Arg 3
Returns:
True or False
"""
return True How do you think pydoclint should handle this case above? |
I'm not sure if it is clearly defined but my understanding is that at least in one place is required, but you could have both too (and in this case it would be good for this tool to check that). |
From the style guide I would think that's valid and this tool should should not raise any errors, but I think it is a obscure-enough case to not prioritize supporting the mixed style if it is too time consuming. |
There could be options to enforce one or the other style (or (dis)allowing the mixed style). This these tools I think there are so many combinations of other tools check or documentation generation tools that handle things differently that it would be impossible to comply with all without having a very fine-grained way to change what's allow and what is not, but again, I would optimize for the most common cases first :) |
Assuming a user set Add a new command-line option, And the existing
And here are the possible behaviors and the expected violations:
What do you think? |
Also, I plan to let this case fail all 4 scenarios: def myFunc(arg1, arg2: int, arg3: str) -> bool:
"""
Do something
Args:
arg1 (str): Arg 1
arg2: Arg 2
arg3: Arg 3
Returns:
True or False
"""
return True Because I personally think this is bad practice. We should either put type hints all in the signature, all in the docstring, or in both. Mixing them is hard to maintain. |
I don' t remember what the options for ˋ--check-type-hintsˋ where but I think it complicates the interface (and maybe the implementation too) to have 2 different options and make options take no effect depending on other options. I would only have one option and make it work for all styles. The, as I said in #14, I would change the defaults based on the chosen style to match that style.
And what happens when functions have types and not docs or viceversa?
I think checking only that signatures have type hints is ˋmypyˋ job, I wouldn't add an option for that according to your philosophy :).
I would call this option signatures-only then.
Sounds weird, but OK.
I consequentially would call this docstring-only
I don' t find that scheme all that useful to be honest. IMHO the most common scenarios probably are:
IMHO the last option is a pretty obscure use case already, I think the google style guide was written when type hints were new. By now if you want to specify type hints I see barely any good reason to do it only in the docs (maybe support very old python versions, but even then you can use ˋ# type: ˋ annotations. In an ideal world I would support it, because again I don' t feel I'm anybody to decide what is good or bad, is just that I think it is rare enough to maybe not be worth the effort (at least until somebody asks for it). Hope you find these insights useful! :) |
Thanks for the suggestions! I came up with a 2nd version:
I know I mentioned that it's Naturally, when both options are True, the type hints need to match. And for your code bases, you can set one of the option to True, and the other to False. Since the default style is numpy, the defaults of these 2 new options will be What do you think of this version? |
Hi @jsh9, you are welcome. I think your newly proposed scheme still forbids valid google-style combinations, you could potentially documents types in the code for one function and in the docs for some other, and in both for a third. If this were my project, as I said before I would go for a more flexible and less pedantic/strict set of options to allow more flexibility to the user, but your proposed flags covers our use case ( For the records, I can see a use case for more flexibility. For example, we started using documentation in the docstrings and the code, but then migrated to only do it in the code. This took a while and for some time the code had mixed styles. Of course doing all in one go is also possible but there might be projects with big code bases where this might not be trivial and might put extra difficulties to adopt About defaults I leave the discussion for #14 :) |
Hi @leandro-lucarella-frequenz , yes, there are different levels of "homogeneity":
I think it's better for linters to promote the first case because that's best practice. And I wouldn't want pydoclint to ever "indulge" the 3rd and the 4th case. You mentioned Case 2 in your comment above, and I think that's a valid use case. So here's what I propose: pydoclint --type-hints-in-signature=True --type-hints-in-docstring=False file01.py file02.py ... file10.py
pydoclint --type-hints-in-signature=False --type-hints-in-docstring=True file11.py file12.py ... file20.py
pydoclint --type-hints-in-signature=True --type-hints-in-docstring=True file21.py file22.py ... file30.py
pydoclint --type-hints-in-signature=False --type-hints-in-docstring=False file31.py file32.py ... file40.py This would provide people a transition period to gradually update the code styles. |
Hi @leandro-lucarella-frequenz : I implemented the new options. The changes are included in v0.0.10. I tried v0.0.10 on your code base "frequenz-channels-python" with the following options:
And I indeed discovered a place where the type hints are flipped:
|
This worked great, thanks! |
This should not fail when using google-style, as it is allowed:
https://google.github.io/styleguide/pyguide.html#doc-function-args
Originally posted by @leandro-lucarella-frequenz in #14 (comment)
The text was updated successfully, but these errors were encountered: