I would say: `_element_constructor_` is an underscored method, so it's not really a public-facing routine: by default it's not the place to put documentation for users (tests and formal description is fine, though). Instead, you'd write the documentation in the class documentation. That would be the documentation of the parent or of the element (note that parents don't necessarily prescribe the type of their elements!)
You could of course special-case its documentation, but in practice that means that there's extra stuff to learn (for developers). How would you make this decorator `element_construction_doc` discoverable for other developers -- i.e., if such a decorator would already exist, how would you think you would have discovered its existence? I'd say the conclusion the relevant documentation should simply go into the class is more easily maintained/transferred/taught/discovered. Is there a reason for developers to be allergic to write more extensive documentation into the class doc directly? On Wednesday, 11 June 2025 at 10:50:18 UTC+2 axio...@yahoo.de wrote: > Would it make sense to have a decorator for `_element_constructor_` that > adds the doc to the `__init__` (or the class) docstring? For example, in > LazySeriesRing: > > @element_construction_doc > def _element_constructor_(self, x=None, valuation=None, degree=None, > constant=None, coefficients=None): > ... > > Martin > > On Wednesday, 11 June 2025 at 02:04:11 UTC+2 tcsc...@gmail.com wrote: > >> Hi Martin, >> Indeed this is a tricky issue because there are two competing forces: >> >> 1 - The construction of elements should lie with the elements, which >> would be accessible via the published html doc and "elt?". >> 2 - The parsing of input to pass to the element is done by the parent. >> >> From purely 1, it is clear where the examples are best: in the element >> class-level docstring. However, this is not easy to access if you only have >> the parent. Pure 2 says put sufficient examples in the parent class-level >> docstring as having it in the _element_constructor_() makes it hidden >> (which is the place for more technical information/tests). However, you >> don't want to repeat stuff, so doing stuff to satisfy completely 1 and 2 >> together is a maintenance burden. >> >> My typical approach is mostly putting a fair amount of examples in the >> parent class-level docstring (usually at least one example showing the >> different parts of the API) to get a sense of how to construct elements, >> having some additional less-technical information in the element >> class-level docstring, and all the technical stuff in the element's >> __init__() and/or parent's _element_constructor_() docstrings. >> >> The other thing to consider is how you expect users to construct >> elements. For the polynomial ring, once you have one example using the >> generator, it is clear how it is expected to be used. Matrices partially >> does what I would do, but it could have a few more examples (and/or >> reference Matrix()). >> >> Best, >> Travis >> >> >> On Tuesday, June 10, 2025 at 12:27:00 AM UTC+9 axio...@yahoo.de wrote: >> >>> Dear all, >>> >>> I am trying to understand how we want to document parents and elements. >>> As an example, consider a user trying to construct a matrix or a polynomial >>> as follows. >>> >>> sage: MatrixSpace? >>> sage: PolynomialRing? >>> >>> yields the class docstring or the class factory, which indeed contains >>> documentation on how to construct a MatrixSpace or PolynomialRing. >>> Everything is looking fine here. So let's do that: >>> >>> sage: M = MatrixSpace(QQ, 3) >>> sage: P.<x> = PolynomialRing(QQ) >>> >>> Now, how do we construct elements? I would expect that >>> >>> sage: M? >>> sage: P? >>> >>> tells me that, but this is not the case. The former again gives the >>> class docstring, the latter gives the Call docstring (which at least points >>> to _element_constructor_). >>> >>> I cannot imagine that a user would actually get the idea of typing >>> >>> sage: M._element_constructor_? >>> sage: P._element_constructor_? >>> >>> So I have the following questions: >>> >>> 1) is there an obvious way to obtain the documentation on how to create >>> elements which I overlooked? >>> 2) if not so, is there a way to improve the situation? >>> >>> In any case, I am guessing that for new structures, this information >>> should still be provided in the _element_constructor_ method. >>> >>> Best wishes, >>> >>> Martin >>> >> -- You received this message because you are subscribed to the Google Groups "sage-devel" group. To unsubscribe from this group and stop receiving emails from it, send an email to sage-devel+unsubscr...@googlegroups.com. To view this discussion visit https://groups.google.com/d/msgid/sage-devel/43ad4031-acb7-4339-b486-467c60da7e9fn%40googlegroups.com.
