Better property support #640
Conversation
…deleters under a single documentation entry.
Codecov ReportAttention: Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## master #640 +/- ##
========================================
Coverage 92.59% 92.60%
========================================
Files 47 47
Lines 8402 8584 +182
Branches 1853 1899 +46
========================================
+ Hits 7780 7949 +169
- Misses 357 366 +9
- Partials 265 269 +4 ☔ View full report in Codecov by Sentry. |
|
|
||
| @property | ||
| def undoc_prop(self) -> bytes: | ||
| """This property has a docstring only on the setter.""" |
There was a problem hiding this comment.
| """This property has a docstring only on the setter.""" | |
| """This property has a docstring only on the getter.""" |
| builder.addModuleString(base_mod, modname='mod') | ||
| builder.buildModules() | ||
|
|
||
| assert not capsys.readouterr().out |
There was a problem hiding this comment.
This should trigger a few warnings.
|
There are several refactors to do for the changes to be clean, it should take less lines and function should created to wrap the properly handing logic while visiting the function defs. And more importantly, I’m unsure if it worth it to support inherited property overrides, like the proposed change currently does. On the one hand, it’s properly covered by tests cases and it’s used in cpython tests, but on the other hand, it’s not very common usage of te property decorators and it adds about 80 lines of code to pydoctor. But I think it’s can’t be bad to support it at the end of the day it’s safe and it doesn’t make pydoctor crash. |
…if we show the .setter function. It must be writable.
tristanlatr
force-pushed
the
587-better-property-support
branch
from
d5fddc4 to
111b669
Compare
This have been done. At the same time, I've added support for |
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
|
The numpy diff bugs me... I'm not currently sure the cause of such a diff. |
This comment has been minimized.
This comment has been minimized.
…ctor into 587-better-property-support
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
…ated with the property() call. Simpler message when a docstring is getting overriden.
This comment has been minimized.
This comment has been minimized.
|
Blockers:
|
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
|
Diff from pydoctor_primer, showing the effect of this PR on open source code: astroid (https://github.com/pylint-dev/astroid)
+ /projects/astroid/astroid/nodes/scoped_nodes/scoped_nodes.py:1869: Existing docstring at line 1771 is overriden
+ /projects/astroid/astroid/nodes/scoped_nodes/scoped_nodes.py:1873: Parameter name missing
+ /projects/astroid/astroid/nodes/scoped_nodes/scoped_nodes.py:2002: Parameter name missing
+ astroid.nodes.Arguments.arguments.getter
- astroid.nodes.node_classes.Arguments.arguments
numpy (https://github.com/numpy/numpy)
- /projects/numpy/numpy/ma/core.py:2751: Cannot find link target for "array_like"
+ /projects/numpy/numpy/ma/core.py:3726: Cannot find link target for "numpy.ndarray"
|
The property setter and deleter informations now shows at the same place as the property getter. Meaning inside the documentation of an
Attributeobject.Fixes #587. Together with #595 it will look better (without the Undocumented param tables).
As a side effect of the change, the setters and deleters
Functionare removed from the documentable tree, we can't look for the property setters in the search bar with*.setter, we can't link to them from docstrings (but still we can link to them with their anchor) and they won't display in intersphinx mapping.This is a breaking change, but that might not be very important. These objects do not actually exists at runtime, so I think it's OK to remove them from the tree.
Before:
After: