Brief and extensive docs with ? and ??

[timholy]

Most methods have short documentation, but there are a few exceptions. It might be nice to have ??foo mean something like "print only the first few lines of help for foo," basically for experienced users to remind themselves what arguments should be supplied in what order. EDIT: or the opposite, long docs with ?? and short docs with ?.

Inspired by some extremely thorough (and useful) documentation in JuliaImages/ImageFiltering.jl#54.

[cormullion]

Users might expect ? to give brief, and ?? more copious, information. (Is this similar to vvv options for Unix commands?)

[yurivish]

Brief docs with ? would be wonderful — I’ve often had to scroll through pages of output at the REPL when I just needed a quick overview.

Additionally, if the brief display became standard it would be a forcing function for the convention of supplying a quick summary sentence at the start of a docstring, which would lend itself well to tooling (e.g. hover a function name in your editor to see a tooltip with the signature and brief description).

[ChristianKurz]

If this is implemented, it would be nice to have separate REPL-modes for brief and full help.

E.g. typing ? would change the prompt to brief help> and adding another ? would change to help>.
Additionally, just entering ? and hitting enter without further text should hint at adding another ? to show full help.

[StefanKarpinski]

I do think that ? for brief default help and ?? for long help would be good (opened in a pager).

[tpapp]

opened in a pager

It would be best if that was customizable, eg for opening nicely formatted HTML in a browser.

[PallHaraldsson]

If this is implemented, it would be nice to have separate REPL-modes for brief and full help.

Is it really needed? Some users know some functions to have long text, but for new users all functions potentially have long docs. Wouldn't something simple like this be ok:

help?> potentially_long_function  # simulated here with: unsafe_pointer_to_objref
search: unsafe_pointer_to_objref

  unsafe_pointer_to_objref(p::Ptr)

  Convert a Ptr to an object reference. Assumes the pointer refers to a valid heap-allocated Julia object. If this is not the case, undefined
  behavior results, hence this function is considered "unsafe" and should be used with care.
PRESS ENTER FOR MORE LINES, or q for no more.

That last line wouldn't actually display for this function, as there's nothing more to display or any function with shorter text than this or 6-8 lines. But for longer ones, if would be there in bold or other color, and be overwritten with the next few lines (or all?) when not-q pressed.

Sometimes I would like docs to display as with, i.e. take the full screen and then disappear and safe screen space (this could be an ENV option, to pipe to e.g. less and potentially a threshold length that would trigger this):

shell> less LICENSE.md

julia>