Hi Stan,
On 16 Sep., 11:25, Stan Schymanski <schym...@gmail.com> wrote:
> On Sep 16, 6:57 am, rjf <fate...@gmail.com> wrote:
>
> > Another way is to establish a storage structure, e.g. hashtable,
> > indexed file, etc
> > to store all the documentation strings with the object names as keys.
>
> > Essentially ?variablename = doctable["variablename"]/
>
> Are you suggesting that such information could be stored with the
> object name? I think that would be nice. So if I typed H_l?, I would
> see the entries for that key in all the dictionaries I defined?
Things like "H?" or "H??" use functions in sage.misc.sageinspect (such
as sage_getdoc). Among other things, sage_getdoc(H) tries to get
information by calling a method H._sage_doc_().
One could add a default method set_custom_doc to
sage.structure.sage_object.SageObject, that makes _sage_doc_ return a
given doc string for a specific instance (not just for the class of
the instance).
Proof of concept:
sage: cython("""
from sage.structure.sage_object cimport SageObject
cdef class SageObjectDoc(SageObject):
cdef str _doc_
def set_custom_doc(self, d):
self._doc_ = d
def _sage_doc_(self):
if self._doc_ is None:
raise AttributeError
return self._doc_
""")
sage: H = SageObjectDoc()
sage: H?
Type: SageObjectDoc
Base Class: <type
'_mnt_local_king__sage_temp_mpc622_20428_tmp_1_spyx_0.SageObjectDoc'>
String Form: <type
'_mnt_local_king__sage_temp_mpc622_20428_tmp_1_spyx_0.SageObjectDoc'>
Namespace: Interactive
File: /mnt/local/king/.sage/temp/mpc622/20428/spyx/
_mnt_local_king__sage_temp_mpc622_20428_tmp_1_spyx/
_mnt_local_king__sage_temp_mpc622_20428_tmp_1_spyx_0.so
Docstring:
x.__init__(...) initializes x; see x.__class__.__doc__ for
signature
sage: H.set_custom_doc('Specific doc for H')
sage: H?
Type: SageObjectDoc
Base Class: <type
'_mnt_local_king__sage_temp_mpc622_20428_tmp_1_spyx_0.SageObjectDoc'>
String Form: <type
'_mnt_local_king__sage_temp_mpc622_20428_tmp_1_spyx_0.SageObjectDoc'>
Namespace: Interactive
File: /mnt/local/king/.sage/temp/mpc622/20428/spyx/
_mnt_local_king__sage_temp_mpc622_20428_tmp_1_spyx/
_mnt_local_king__sage_temp_mpc622_20428_tmp_1_spyx_0.so
Docstring:
Specific doc for H
Class Docstring:
x.__init__(...) initializes x; see x.__class__.__doc__ for
signature
One problem is, however, that SageObject must not have cdef
attributes, because otherwise sage.structure.sequence.Sequence_generic
(which inherits from SageObject and list) can not be defined.
Suggested work-around: Define set_custom_doc and _sage_doc_ not for
SageObject, but for sage.structure.parent.Parent and
sage.structure.element.Element.
Other approach: One could have set_custom_doc as a method of
SageObject, but the value is then stored in a dictionary _custom_docs
in sage.misc.sageinspect, so that H.set_custom_doc(d) stores
sage.misc.sageinspect._custom_docs[id(H)]=d.
And then, sage_getdoc could be modified to first look into
_custom_docs[id(H)], before calling H._sage_doc_().
Do people think that it would be a good additional feature? Which of
the two approaches seems better?
Best regards,
Simon
--
To post to this group, send an email to sage-devel@googlegroups.com
To unsubscribe from this group, send an email to
sage-devel+unsubscr...@googlegroups.com
For more options, visit this group at http://groups.google.com/group/sage-devel
URL: http://www.sagemath.org
