On Thu, Aug 9, 2018 at 4:46 PM Erik Bray <erik.m.b...@gmail.com> wrote:
> On Thu, Aug 9, 2018 at 4:26 PM William Stein <wst...@gmail.com> wrote:
> >
> > On Thu, Aug 9, 2018 at 6:20 AM, Simon King <simon.k...@uni-jena.de> wrote:
> > > Hi Eric,
> > >
> > > On 2018-08-09, Erik Bray <erik.m.b...@gmail.com> wrote:
> > >> But it got me thinking: Maybe it would actually be nice if most Sage
> > >> classes--or at least those inheriting from SageObject, had some
> > >> version of this .help() method.  Although we already do a decent job
> > >> advertising the ? and ?? syntax, having  .help() method is inherently
> > >> more discoverable (an the help methods in sandpiles even advertise the
> > >> ? syntax for further details).
> >
> > I would move anything in a help method to docstrings and deprecate
> > these help methods.
> > Docstrings is where documentation in the source code belongs.  It
> > sounds to me like these
> > help methods generate documentation that is NOT included in the
> > reference manual, and
> > that people who know about docstrings mainly might not find.
> Did you read my follow-up to Simon?  It does not generate
> documentation that is not included in the reference manual.  These
> contents of these .help() methods are generated from the docstrings of
> the classes' methods as you can see in the example I posted.  It's
> just a different, and more succinct (you should like that!) way of
> displaying the same information that already exists.  It also points
> the user to the '?' syntax for more information.
> > > I think such method would be fairly useless.
> > > Reason: If a user seeks help about X by trying X.help() rather than
> > > help(X) apparently knows about methods, as a corollary knows about
> > > Python, and as a corollary knows about ? and ??.
> > >
> > > While a .help() METHOD seems useless to me, a help() FUNCTION might be
> > > useful for newbies. Say, help(X) could print a pointer to the "?" syntax
> > > (so that the newby will soon be a bit less newby) and then print the doc
> > > string of X.
> >
> > There is a help function *built into Python* already.  That's why Sage says:
> >
> > 'Type "help()" for help.'
> >
> > on startup.
> That is helpful! It should probably also say something about
> tab-completion.  However, while help() with no arguments displays some
> custom help text for sage, help(<obj>) just seems to fall back to the
> default Python help(<obj>) functionality, which does *not* have the
> Sage-specific enhancements we make to the <obj>? help.
> It would probably be better, at the very least, if "help(<obj>)" an
> "<obj>?" were identical, and not confusingly different.  (Also, the
> "<obj>?" syntax is unique to IPython, so even someone familiar with
> Python but not much IPython experience might not know it).
> Anyways, I'm not in love with the idea or anything but it seems more
> helpful to users to have more ways to get help.

One other thing I noticed is that Python's default `help(Integer)`
gives you all the methods defined on Integer as well as their
docstrings, where as `Integer?` just gives the class docstring, but
does not list the methods.

So if you want to look up all the methods on an object, the only way
seems to be `help(<obj>)`, which is confusingly different (to a user)
from `<obj>?`, or tab completion with `<obj>.<tab>` which can be
tedious, hard to search through, and not always accessible.

Am I missing something?  If I want to list all the methods an
attributes of an object in Sge, what is the best way to do that

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 https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Reply via email to