documentation of parents and elements

[Martin R]

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

[Travis Scrimshaw]

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

[Martin R]

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

[Nils Bruin]

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?