@property inconsistently documented

[rpitasky]

Problem Description

Our codebase uses a lot of @property and we're seeing that only some of these are documented.

Most curious to me is the fact that TIEntry.data_length is documented while the other @propertys are not.

Steps to reproduce the behavior:

1. Save the following minimal code to bug.py

class Bug:
    @property
    def a(self):
        return "a"

2. Run pdoc on it (I use python3 -m pdoc bug.py but our CI does it normally, but I doubt this matters)
3. Observe that the @property code is not documented.

System Information

Paste the output of "pdoc --version" here.
pdoc 13.1.1, python 3.10

[rpitasky]

It looks like the issue is that the @properties don't have docstrings; I find this behavior rather curious.

What is the justification for the default being to not document these?

[mhils]

See #280 and #411 - that should give you some background. I guess I hold no super strong opinions here. :-)

[kg583]

I don't have strong opinions about the choice of intended behavior either (everything that needs to be documented should be in the end), but there is still inconsistency.

According to #280, "pdoc documents all attributes that have either a docstring or a type annotation." (emphasis mine), but properties are only being documented if there is a docstring and type annotation. Indeed, this property has both while this property is only annotated, and only former appears in the docs.

[mhils]

#280 is older than #411, see mhils@a6f21be

[rpitasky]

Thank you for your rapid responses. Well, that's certainly a conundrum- you have users with diametrically opposing positions here! I guess my opinion coming into this was that (by default) everything should be documented. I personally prefer this because it shows developers explicitly what still needs documentation, and at least half of the utility of code documentation for users is to show what exists.

Perhaps this whole issue could be resolved through additional documentation in pdoc's Quickstart. This could be easily be roped into the opening beats; I propose editing the Quickstart example to include something with neither type annotations or a docstring and changing

If you look closely, you'll notice that docstrings are interpreted as Markdown. For example, `pdoc` is rendered as pdoc. Additionally, identifiers such as the type annotation for Dog.friends are automatically linked.

into

If you look closely, you'll notice that docstrings are interpreted as Markdown. For example, `pdoc` is rendered as pdoc. Additionally, identifiers such as the type annotation for Dog.friends are automatically linked. Items without type annotations or docstrings are omitted by default, but they ccan be included by <insert-way-to-change-this-default-here-if-it-exists>.

(or a derivative of the above that doesn't dramatically alter the flow of the whole section), with the additional subtleties being noted under the "How can I document variables" section. I think this is a fundamental enough design choice that it deserves a prominent spot on that page.

[kg583]

#280 is older than #411, see mhils@a6f21be

Ah, I didn't quite pick that out of the thread.

It does nonetheless feel a bit weird for the case of properties, since although they act like variables in syntactic respects, being a @property communicates the fact that this is a value the user could want to fetch, in contrast with an instance variable which might be user-facing or might not be (if not made explicitly private). And although there should be a docstring, presumably one could have a property with a sufficiently self-documenting name and return type.

[mhils]

Thank you two! I think there's a strong argument that variables shouldn't behave any other from functions or classes in terms of default visibility. I've just pushed #575, which makes it so that variables are documented by default - irrespective of whether they have a docstring or not. I've linked this issue in the changelog - if someone comes up with a convincing use case for why this is particularly annoying, we might add a --documented-only flag or something like that. Let's see! 😃

[mhils]

Forgot to update here - this should be fixed with pdoc 14! 🍰