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
currently?

-- 
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