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/49d8f904-de1c-4540-89a0-7ed824f63fa1n%40googlegroups.com.
