William Stein wrote:
> On Tue, 12 Dec 2006 10:27:16 -0800, Nick Alexander <[EMAIL PROTECTED]>
> wrote:
>
> > Hi William,
> >
> > An oddity in ref.pdf. Pyrex filenames get embedded in the output, as
> > in:
> >
> > inverse mod()
> > File: sage/rings/integer.pyx (starting at line 1671)
> >
> > Is that on purpose?
>
> No. That is a result of a change in SAGE -- namely I added an option to
> SAGEX
> so it records the file and location where functions are defined. This is
> used at runtime for source code viewing, and displaying correct functions
> headers.
> The update_script.py script doesn't know about this change. It could be
> used
> to improve the quality of ref.tex (e.g., find the function headers easily).
I would very much like to enhance sagex to embed _more_ information
about cdef'd functions. At the moment, the python inspect module gives
very little information about them. While we might not be able to
include code pointers, etc, we can definitely include arguments and
default values. I'd like to use that information for better formatting
and better tested documentation, but it would also make for better
inline help.
I envision making docstrings hash tables, i.e. such that eval(__doc__)
returns a dict. Your patch would be upgraded to make the docstring
r"""
{ 'im_class' : 'sage.blah.module.Class'
, 'im_func' : { 'attributes about function' : 'blah' }
, '__doc__': 'original docstring'
}"""
etc.
There are downsides. First, we're carting around a lot of information
in the docstrings. There's a space penalty, and also a
not-using-the-natural-structure penalty. I think docstring has to be a
string, though, so we're stuck. If it can be an object with a
__repr__, I'd be much happier. Second, we'd be parsing the docstring
ourselves or calling eval. One tends to be a little brittle, the other
a security hole.
Let me know what you think,
Nick
--~--~---------~--~----~------------~-------~--~----~
To post to this group, send email to sage-devel@googlegroups.com
To unsubscribe from this group, send email to [EMAIL PROTECTED]
For more options, visit this group at http://groups.google.com/group/sage-devel
URLs: http://sage.scipy.org/sage/ and http://modular.math.washington.edu/sage/
-~----------~----~----~----~------~----~------~--~---
