No class comments

[JesseWebDotCom]

Example: https://timothycrosley.github.io/portray/reference/portray/exceptions/

How come class comments do not display?

[simonvanderveldt]

Can confirm, this seems to be a regression introduced in version 1.5.0
We're sticking to 1.4.0 which correctly shows the comments from the class because of this.

[Mike-Powell-ConcertAI]

Thanks simon, same issue -- i reverted to v1.4, and it worked fine.

[geniashand]

I see that it wasn't solved in version 1.7.0
Should I just use the 1.4.0 version?

Also, I tried to search for the bug but couldn't find it. If someone would guide me where to look I could try and fix it.

[simonvanderveldt]

@geniashand I haven't had time to dive into it, so can't give you much with regards to pointers unfortunately.
It seems like there are unfortunately no github releases nor tags for portray, but looking at the commits and assuming it's indeed a regression introduced between 1.4.0 and 1.5.0 it should be one of the changes between these two commits
e45d114...0ffc51a

[ARBaart]

@simonvanderveldt One of those commit ( 507d2f5 ) is bumping pdocs from 1.0.2 to 1.1.0, which is the package actually writing the markdown files based on the docstrings. So it's commit 507d2f5 in this repo, but the underlying issue would be found somewhere in the pdocs commits between 1.0.2 and 1.1.1

[ARBaart]

Okay I figured it out:
In pdocs 1.0.2 due to a typo the parsing of docstrings (to extract params/returns) would always fail so you'd get the docstring displayed as-is. Going into 1.1.0 they fixed that by fixing the typo, but the display of a class's docstring doesn't include its short or long description, only the params.

So say your class is something like:

class Example:
    """This is the short description which is just the first line.

    Here is room for a longer description where you can go
    into detail on multiple lines if you like.

    :param value: A description of the param.
    """
    def __init__(value):
        self._value = value

Before it would print the thing as-is, with no formatting for that param. Now it succeeds in parsing it, but only displays the params, skipping the short and long description. And if you have no params in your docstring, it just displays nothing.