Properties are shown as var

[johann-petrak]

The generated documentation for a property:

@property
def weight(self) -> int:
...

is shown as "var weight : int" but it would be more useful if the fact that this is a property would get shown, e.g.
"property weight: int" as the Sphinx generator does.

This is also shown under the header "Instance variables" which is not exactly right.

Also, if there is a separate setter for the property:

@weight.setter
def weight(self, weight):
...

this is not reflected in the documentation, so there is no way to see from the documentation if the property can only be read or set as well. Only the docstring of the getter method is included in the generated documentation.

[kernc]

This part came from the original pdoc and so far hasn't been touched (or, at least, revised into a different manner). We only know about not even a handful of objects: modules, classes, functions and variables.

pdoc/pdoc/__init__.py

Lines 985 to 993 in d776cbd

	self.doc[name] = Variable(
	name, self.module,
	docstring=(
	var_docstrings.get(name) or
	(inspect.isclass(obj) or _is_descriptor(obj)) and inspect.getdoc(obj)),
	cls=self,
	obj=getattr(obj, 'fget', getattr(obj, '__get__', None)),
	instance_var=(_is_descriptor(obj) or
	name in getattr(self.obj, '__slots__', ())))

It's a major simplification, which I kind of like, but otherwise agree with all your points. 😕

[johann-petrak]

Hmm, I do not know much about Python internals but for a member of some class C, I think it is not too hard to find out of the
member is a variable or property:

class C1: 
     a = 1 
     def b(self): 
         return 2 
     @property 
     def c(self): 
         return 3 

def whatisit(clazz, membername): 
    return dict(inspect.getmembers(clazz))[membername]

assert isinstance(whatisit(C1,"c") property)

So this could still get listed under "Instance variables" but with a prefix "property" instead of "var".

It is probably harder to figure out of the property also has a setter or not. If this can be done, then it would be cool to have "read only property" in the docs if there is no setter and otherwise just "property", I think. Or some other way to indicate this.

[kernc]

Unlike pdoc.Function.funcdef():

pdoc/pdoc/__init__.py

Lines 1235 to 1240 in d776cbd

	def funcdef(self) -> str:
	"""
	Generates the string of keywords used to define the function,
	for example `def` or `async def`.
	"""
	return 'async def' if self._is_async else 'def'

the 'var' before variables comes from the template:

pdoc/pdoc/templates/html.mako

Lines 235 to 237 in d776cbd

	% for v in inst_vars:
	<% return_type = get_annotation(v.type_annotation) %>
	<dt id="${v.refname}"><code class="name">var ${ident(v.name)}${return_type}</code></dt>

And that's not the place for further complex logic. (Although you're welcome to suit it to your needs.)

It's not hard to discern properties, access setters too, but there's currently no extra supporting API in place; this would probably not be a minor/trivial change. But if you're willing to work on it, I'd certainly have a look!

The reasoning behind properties being instance variables is that they do, normally, depend on (some computation upon) self.

[johann-petrak]

Thanks!

I have implemented something for this which works for me but I am not sure that I have not overlooked
some important cases or situations I am less familiar with.

The concrete way how to show this is obviously a matter of taste. I would very much like it if the documentation would indicate read-only properties (which only have a getter) vs. other properties which may have a setter and/or a getter.

In my fix i have called the former "ro-property" and the latter just "property".

See #277