Opened 4 years ago

Last modified 4 years ago

#26041 new enhancement

Improve functionality of help(<obj>)

Reported by: embray Owned by:
Priority: major Milestone: sage-wishlist
Component: documentation Keywords:
Cc: nthiery Merged in:
Authors: Reviewers:
Report Upstream: N/A Work issues:
Branch: Commit:
Dependencies: Stopgaps:

Status badges

Description

We already override the built-in help() function from Python with our own that prints some useful help text when it's called without arguments.

However, when called with arguments like help(Integer) it just uses the default Python help() implementation, and not the help provided through the IPython <obj>? syntax.

That said, help(<obj>) is sometimes more informative as it lists all the methods on an object and their docstrings as well (sometimes this is too informative if you just want a summary of methods). Whereas <obj>? typically just lists the docstring of the object's class, but not documentation for methods or attributes.

Meanwhile <obj>?? is almost always too much. It displays the full source code of the object's class, which is great when you want to see it, but too much information for general help purposes.

From a UX perspective I believe there's no reason help(<obj>) and <obj>? should do different things. As it is it's more than one way to do a thing, and it shouldn't have different results--the user is force to remember which syntax they want to use to get different levels of information, and there's no obvious reason for the present distinction.

So I would be for merging the functionality of help(<obj>) and <obj>?--make them do the same thing, and also make whatever it is they do informative.

See discussion at

https://groups.google.com/d/msg/sage-devel/ROHhcIHcxpc/FSKrD-kiDQAJ

and also a related ticket #20589.

Change History (1)

comment:1 Changed 4 years ago by embray

  • Component changed from PLEASE CHANGE to documentation
Note: See TracTickets for help on using tickets.