On Fri, Aug 10, 2018 at 12:25 PM John Cremona <john.crem...@gmail.com> wrote:
>
>
>
> On 10 August 2018 at 11:13, Erik Bray <erik.m.b...@gmail.com> wrote:
>>
>> 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.
>
>
> Here's one thing which might confuse beginners using help().   For integers, 
> help(Integer) and help(0) give the same output (which is of course different 
> from help(int)).  But in general you may see different things when objects 
> are not constructed via the class name.  For example help(NumberField) gives 
> information about the NumberField constructor, while after creating one, say 
> with K=NumberField(x^2+1,'i'),  help(K) gives you the methods for that object 
> as well as telling you that it's type is NumberField_quadratic_with_category.

I've never liked that there are constructors in Sage that are
functions but look like class names.  I'd rather NumberField itself
were a class, with NumberField.__new__ acting as the factory.  I
suspect there is a reason it wasn't done that way but I was never
clear on that.  I'm also not sure whether or not it would help with
that problem since even if NumberField were a class, it may have
different docs than something like a
NumberField_quadratic_with_category that it might output.

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