I put all such documentation at the class level for the parent (although sometimes in the EXAMPLES:: block). Although anything that's more of an implementation detail I leave in the _element_constructor_().
Best, Travis On Wednesday, April 9, 2014 6:20:09 PM UTC-7, Nils Bruin wrote: > > It came up on sage-support that some element constructor documentation is > rather hard to find: > > https://groups.google.com/forum/#!topic/sage-support/FIqaVz1tgyk > > and since solving this issue is a development problem, I'm reposting here. > > In short, given > > R.<x>=QQ[] > > how to find that R([1,2,3]) creates 1+2*x+3*x^2 ? > > The most likely spot seems to be R?, which indeed also displays the > docstring of R.__call__ ; the relevant method. However, the actual method > there is only a generic one, which has a basically useless docstring. The > actual work is deferred to R._element_constructor_, which doesn't happen to > have a relevant example, but it would seem the right place to add it. The > problem now: _element_constructor_ is an underscore method, so it's made to > be poorly discoverable. Yet, it is the canonical place to document element > construction peculiarities of R--very relevant documentation. How can we > make that documentation more readily available? should we list it under R? > as well? > -- 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 post to this group, send email to sage-devel@googlegroups.com. Visit this group at http://groups.google.com/group/sage-devel. For more options, visit https://groups.google.com/d/optout.
