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

D100 claims module is public when it is prefixed _ #199

Closed
jayvdb opened this Issue Jul 26, 2016 · 8 comments

Comments

Projects
4 participants
@jayvdb
Copy link
Member

jayvdb commented Jul 26, 2016

Module.is_public is hardwired to True, which means the following occurs

html5lib-python/html5lib/_inputstream.py:1:1: D100 Missing docstring in public module

Processing modules like this raises lots of other terminology problems, such as : should a class/def without a _ prefix in a private module be considered "public".

A simplistic approach is to simply not process modules beginning with _ unless they are __init__, both in the pydocstyle main() and hope flake8-docstrings does the same.

@Nurdok

This comment has been minimized.

Copy link
Member

Nurdok commented Jul 28, 2016

Thanks for reporting this.
The simplistic approach you suggested is bad, since while a private module does not HAVE to have a docstring, if it does, it MUST be legal, so that module should be processed.
Module.is_public should probably change to be the same as Class (underscore means private).

@jayvdb

This comment has been minimized.

Copy link
Member

jayvdb commented Jul 28, 2016

Nod.
And a non-_-prefixed class/def in a _-prefixed module...should it be treated as a public object?

@Nurdok

This comment has been minimized.

Copy link
Member

Nurdok commented Jul 28, 2016

When checking for publicity of definitions, the logic is that it is public as long as all of its parents are public AND it doesn't begin with an underscore. So "public named" classes in a private module should be considered private and do not necessitate‬ a docstring.

@larsoner

This comment has been minimized.

Copy link
Contributor

larsoner commented Sep 4, 2016

So "public named" classes in a private module should be considered private and do not necessitate‬ a docstring.

One problem with this is that it's easy to do in __init_.py from ._whatever import public_function, and thus the function could appear public when actually used by a user (as opposed to during development). I don't see an easy solution to this problem, though.

@jayvdb

This comment has been minimized.

Copy link
Member

jayvdb commented Sep 4, 2016

Yea. that is a common and sensible/desirable pattern.

IMO '_'-prefixed modules should not be processed differently. Any other approach opens a can of worms.

If the prefix means docstrings are optional, the more sensible approach is to ignose those files using config options if necessary, as they will also be skipped by most documentation tools, or writing quality docstrings and checking the module as if it was public. We could have a simple config option to ignore private modules, disabled by default which is the current behaviour.

However the messages should at least not say "public module" etc, and maybe should have different error codes for finer tuning.

@varunagrawal

This comment has been minimized.

Copy link
Contributor

varunagrawal commented Oct 10, 2016

I'll handle this.

@varunagrawal

This comment has been minimized.

Copy link
Contributor

varunagrawal commented Oct 17, 2016

@jayvdb I should just add a config option to ignore all modules beginning with a '_' and have it disabled by default?

What else would you recommend I do?

@jayvdb

This comment has been minimized.

Copy link
Member

jayvdb commented Nov 3, 2016

Hi @varunagrawal , I would start by detecting private modules, and at least reporting them as 'private' instead of 'public'. That is what this bug is about.

Once the 'private module' detection algorithm is bedded in, with at least a minor release or two of field testing, new approaches for handling members of private modules can be introduced.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment