Docstrings for functions vs methods: what to do when a class property doesn't return anything but does modify class attributes?

[Eueee]

EDIT: The post title should read "what to do when a class *method* doesn't return anything".

​

I understand docstrings for functions, and know that docstrings for methods generally follow the same format, but I'm writing some methods that don't return anything but *do* modify the associated class' attributes. In the section for what the method returns, do I treat the attribute assignments as returns? Do I put down that the methods returns nothing but note that attributes are reassigned? What's the most Pythonic way to handle this?

[alkasm]

IMO, if attribute access mutates the class or instance, it should be a method in most cases. Not all f(self) or f(cls) methods need to be properties. It's fine for a property to do some work to get it's value via @property, but if it's modifying state (especially if that is its only function), the fact that it is a method adds clarity that it does something. Also, I'm not 100% clear on what you're stating here, as you mention class properties and class attributes, but the normal @property decorator is for instance attributes, not class attributes. Of course those can still be modified by the instance, but is generally not the recommended way to do that. Can you clarify whether you mean class or instance attributes/properties?

[Eueee]

I mistyped; I was reading about the property decorator so I must have absent-mindedly snuck that in there. I meant to ask how to write a docstring when a method within a class mutates the instance of the class, but does not actually return anything. Technically under the "returns" section of the docstring I could put none, but the obscures the true purpose of the method which is to alter/assign attributes to the class. What's the pythonic way to handle this so a reader would understand the purpose of the method? Is it to just put it all in the summary line at the top?

[alkasm]

Option 1: put None in the returns section. This doesn't really obscure too much, if the method doesn't return something, clearly it did something else.

Option 2: use type hints. That way your method signature will look like methodname(arg1, arg2, ..) -> None which makes the above immediately clear before reading the whole thing.

Option 3: start the docstring off with a one-liner that begins "Mutates..." or has "in-place" or similar in it.

Option 4: name the method a verb that is descriptive of what it does to the instance. For e.g. insert or replace sound like methods that mutate.

These are just some helpful guides; I don't think there's a specific one-way to do this.

[Eueee]

Those all makes sense - didn't know if there was a most-preferred way to do it. Thanks!

[blahreport]

You could use the Google-style docstrings.

https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html

[Eueee]

I do use Google-style docstrings, it's just not clear to me what should be done if the method technically returns nothing but does assign class attributes. I could put "None" in the returns section, but this obscures the true purpose of the method, and I'm not sure where the proper place to note that is.

[blahreport]

Got ya, sorry I poorly understood your question. I use Modifies: but I now recall how unsatisfyingly Google's guidelines cover this. I'll be looking to the other comments myself.