Nikita Nemkin, 20.04.2013 16:44: > On Sat, 20 Apr 2013 17:41:56 +0600, Stefan Behnel wrote: >> Nikita Nemkin, 20.04.2013 12:43: >>> On Sat, 20 Apr 2013 14:27:12 +0600, Stefan Behnel wrote: >>> I did document them manually at first. It is ugly (function doc in one >>> place, attribute doc in another) >> >> As it should be. The attributes are part of the class documentation, >> whereas the function/method documentation belongs to the functions. I can't >> see why you consider this totally normal distinction "ugly". > > Why should attributes and especially properties (class members) be treated > differently from methods (class members) for documentation purposes? > From the OOP standpoint they certainly should not. Smalltalk and Java are > good examples. (Smalltalk even has a documentation convention extremely > similar to Python docstrings.)
Just because some languages don't have properties and always require you to implement getters and setters doesn't mean that attributes, methods and properties are the same thing. The question whether an attribute is implemented as a field or a property is an implementation detail that shouldn't have an impact on users. That makes attributes different from methods. Thus my comment that attributes should be part of the class documentation. That way, you can document them consistently for both extension types and Python classes. Because in the best case, users shouldn't have to care about that distinction either. And with PEP 362 in place, there'll no longer be a need for automatically embedded signatures etc. either. Attributes can be documented as part of the class and methods document themselves anyway. >> All I'm saying is that docstrings for cdef attributes are a very special >> case. If you had a Python class in a Cython module, you couldn't add a >> docstring to its attributes at all. And there already is a dedicated syntax >> for non-trivial properties in cdef classes. So the question is: is a >> property with a docstring still a trivial property or not? And is the use >> case common enough to complicate the simple special case that already >> exists, even though the completely general case can already be handled? > > "cdef public" is one of the two forms of property declaration in Cython. > (The other being "property: ...") Both use nonstandard Python syntax and > neither seems a "special case" to me. "cdef public" is the special case because it's pure syntactic sugar that is redundant with the most simple application of the property syntax. > The property is trivial iif its code consists of one __get__ > function with "return self.value" body. What does docstring have to do > with it? The general way of doing it (i.e. the property syntax) already has a way of specifying a docstring. That's a reason to be hesitant about adding this feature also to the (currently) simple short-hand special case syntax. > "property:" is not completely general. I wont rename every > single public attribute for the privilege of attaching a docstring > to it (and a ton of boilerplate code). It makes no sense from > technical and maintenance standpoint. I agree that it might seem overkill. > Considering use cases. Currently I have 83 cdef public/readonly attributes > across 46 classes that represent ~20% of the source codebase. > All of them have docstrings (since they are public and part of the API.) That seems a lot to me. I wonder how common this actually is. In the code I've written so far, the trivial case of 1:1 properties was pretty rare. Might be a domain thing. Stefan _______________________________________________ cython-devel mailing list cython-devel@python.org http://mail.python.org/mailman/listinfo/cython-devel
