Lisandro Dalcin, 10.03.2010 21:17:
>>> We could get rid of structmember.h by using the transform+property
>>> machinery Dag implemented long ago
>
> Any suggestions about docstring generation? I mean:
>
> 2) The actual contents of the docstrig: currently it is: "attribute
> 'NAME' for 'CLASS' objects"... But it could also be "'TYPE' 'NAME'",
> where 'TYPE' is the C type of the member (so the rendering would be
> like the one for function arguments)
First of all, there doesn't have to be a docstring. CPython won't generate
one for you either, not for '@property' and not for class/instance attributes.
That being said, if we already have to generate a descriptor, and since you
currently can't assign a docstring to a class field at all, I wouldn't mind
adding some information to it that provides at least the (C-)type of the
value that is returned. Given that you can't copy/move this kind of
property to a different class, providing the names of the attribute and its
defining type doesn't sound unreasonable (I assume the class name would be
the current type, not the base type the really defined it). If we ever
support default values, that should go in as well.
So I could imagine providing this:
"CTYPE F.Q.CLASSNAME.ATTRNAME[ = DEFAULT]"
([] meaning 'optional') which basically mimics the complete definition.
I wouldn't mind letting the class name out of this, though, as the only way
to get to the property docstring is through the class or instance, so it
doesn't really add anything and makes the output look more verbose. So IMHO
it would be cleaner to stick to this:
"CTYPE ATTRNAME[ = DEFAULT]"
An alternative is the argument type annotation syntax in Py3:
"ATTRNAME : CTYPE [ = DEFAULT]"
I have a preference for the last one, as it looks very readable: name
first, potentially lengthy C definition follows after a clear separator,
arbitrary default value last, after another clear separator. And since this
is meant to be read in Python space, this is the syntax that Python users
will be more used to. It also makes it easy to parse and to prepend the
FQCN if people ever feel the need to process the docstring in their code.
> 1) Should the docstring be generated inconditionally, or under the
> control of 'embedsignatures' ?
If we provide the definition as docstring, requiring 'embedsignatures'
sounds like the right thing to do. Note that the above may be considered
leaking implementation details (C type and default value) and the embedded
string also implies a a tiny bit of overhead for the module, so some users
may want to disable it.
Stefan
_______________________________________________
Cython-dev mailing list
[email protected]
http://codespeak.net/mailman/listinfo/cython-dev
