Support docstring inheritance in editor?

Answered

Consider the following code:

class A:
""" Parent docstring """

def foo(self):
""" Method docstring """
pass


class B(A):

def foo(self):
pass

 

PyCharm editor raises 2 warnings:

  1. Missing docstring at B class-level
  2. Missing docstring at B.foo method-level

Documentation reference generators such as Sphinx allow B & B.foo to inherit A & A.foo docstrings automatically.
How can the same thing be achieved with PyCharm editor? e.g. if no docstring was added to B.foo, use/show A.foo inherit docstrings instead.

 

6 comments
Comment actions Permalink

Hi Abraham, the inspection is too straightforward unfortunately, it's impossible to disable it only for such cases. The only way, for now, is to turn it off globally. I created a ticket in PyCharms' bug tracker PY-30967 to cover this issue, please feel free to vote/comment.

0
Comment actions Permalink

Hi Pavel, thanks for the quick reply.

Actually I wasn't aiming for disabling this specific-case inspection, but instead - for the parent docstrings (i.e. A.foo docstrings) to be inherited and exposed properly by the editor - at the child level (i.e. B.foo).

e.g. same result like @inheritDoc in java/javascript.

 

0
Comment actions Permalink

Hm, PyCharm should show an original docstring for B.foo, e.g. calling Quick Documentation action (F1):

Doesn't it work the same for you? Could you please specify PyCharm version you are using?

0
Comment actions Permalink

You actually right, the original docstring does appear properly when pressing F1, but in my case, it appears with a warning message first:

PyCharm professional 2018.1 (#PY-181.5087.37 May 24, 2018)

So both the editor warning indication ("Missing docstring") and the documentation popup warning indication ("Documentation is missing")  should be subject to disabling, at least at the project level, in case the parent method/class has docstrings.

 

0
Comment actions Permalink

I've voted for issue PY-30967 - thanks, Pavel.

But it seems like we might want more than that. If you want to add to the documentation for the parent, to note something specific to the child, it would be nice to be able to do that in such a way that it would be easy to see both pieces of documentation.

It might even make sense to have some sort of standard (PEP) around that to define a keyword like (INCLUDE_PARENT_DOCUMENTATION) which could be included as text in the child docstring, indicating to pydoc, the IDE etc that the parent doc is relevant and should be included when documentation for the child is displayed.

0
Comment actions Permalink

I am also interested in something similar to this.  When a Class is created from another it would be nice if this 'class code' would be read/understood by Pycharm

class A:
"""
Class A Docstring
"""

class B:
"""
Class B Docstring
"""
__doc__ += A.__doc__


In the above when using help( ) you get a formatted full string of both classes.  Pycharm doesn't seem to see that code snippet.  I've checked another IDE does seem to support this. 

 

In Charm I think B will display 'Class B Docstring' but not 'look for' the other classes data since it's not specifically necessary.

 

PyCharm 2019.2.3 (Professional Edition)
Build #PY-192.6817.19, built on September 25, 2019
Licensed to Deep Silver Volition / Nathan Turner
You have a perpetual fallback license for this version
Subscription is active until November 9, 2020
Runtime version: 11.0.4+10-b304.69 amd64
VM: OpenJDK 64-Bit Server VM by JetBrains s.r.o
Windows 10 10.0
GC: ParNew, ConcurrentMarkSweep
Memory: 1979M
Cores: 16
Registry:
Non-Bundled Plugins: CMD Support, IdeaVIM

0

Please sign in to leave a comment.