About documenting properties

[almarklein]

Our materials (and a few other classes) have a lot of (settable) properties. We have made a point to make it possible to set each property at object instantiation, e.g. LineMaterial(dash_pattern=[0, 3], color='red').

This means there are two places to document each property:

• In the docstring of the property itself.
• In the Parameters section of the docstring of the class.

I don't think we want these to be a copy of each-other. But what would be a good rule of thumb to follow?

My thoughts:

• A short one-line summary in both cases.
• Detailed explanation in the property docs.
• For enums, list the possible values in both cases.
• For somewhat complex values (e.g. dash_pattern) refer to property docs. Maybe provide small example.
• Default value in the parameter docs.

[almarklein]

Rethinking this: Let's just make a point to add each property to the constructor, with its default value. But in the class docs we simply say that properties values can be passed as keyword arguments.