We should offer ?REPL in the REPL

Internals & Design
1

There is much helpful with the REPL. “?REPL” would serve many well.

1 Like
2

Or just ? (with nothing else)

2 Likes
3

You can already type ? at the help prompt (type ??<enter>) and it gives a couple of documentation links.

help?> ?
search:

  Welcome to Julia 0.5.0. The full manual is available at

  http://docs.julialang.org/

  as well many great tutorials and learning resources:

  http://julialang.org/learning/

  For help on a specific function or macro, type ? followed by its name, e.g.
  ?fft, or ?@time, and press enter.
3 Likes
4

@stevengj got that … given that Julia’s REPL is broad common ground and it is the situated present from whence many of us find first stirrings of anticipatory excitement and comfort from the harsh otherness of most general purpose manners of programming … my thought is that we need:

@dpsanders
julia> ? shows me a shallow-leveled outline of terms, commands, macros and keyboard shortcuts so I may know to do:

julia> ?interactive to see that I can type the first few letters of something and uparrow to its entirety that I had entered last week.
And ishow me the term keys so I know to use julia> ?keys to re-familiarize myself with the latent power that is our REPL.

An open hand extends one’s reach. Julia’s too.

_

1 Like
5

While learning Julia, I have often found the REPL help system… wanting.

REPL help is great if you already know the name of a method, but rather less helpful if you do not know the exact method name or package it is located in. I find that apropos("foo") is not always the best way of getting around either.

Yes, a user can search the Julia docs, but that will not help him/her determine what is available right now in his/her particular Julia installation. And package listings are all on separate github pages with no common API documentation (like doxygen or javadoc). The REPL has access to package docs, but no simple and obvious way to peruse them per package.

In my opinion, the REPL help ??<enter> should quickly show the user how to:

  • list functions names exported by a given package along with their short description strings, defaulting to Base.
  • list type names exported by a given package along with their short description strings, defaulting to Base
  • list the method signatures defined for a particular function name [methods(foo)].
  • list the package[s] exporting a given type or method
  • how to use which to locate method definitions.

The REPL help listing could also use a slightly better buffer than a simple dump. The interface could be similar to the less or man command, pausing at each screen-full and allowing search terms with '/'.

3 Likes
6

Possibly related observation:

At the help prompt, giving a base package name (Pkg, Dates, etc.) gives “README.md not found”

help?> Pkg
search: Pkg

  No documentation found.

  No README.md found for module Base.Pkg.
1 Like
7

PRs for better documentation are always welcome. This is an easy way to contribute that doesn’t require a lot of technical knowledge of Julia internals.

e.g. adding help for Pkg is just a matter of adding a docstring before module Pkg in the source code. Pkg is already well documented in the manual, so the docstring just needs to be an abbreviated summary.

(Docstrings were only added in Julia 0.4, and they still haven’t been written for a lot of pre-existing functionality.)

3 Likes
8

Thanks, @stevengj. It was not clear to me what needed to be done (I tried what was suggested by the message, adding a README.md to the /pkg directory, and re-maked the documentation, and that didn’t work), and I had asked what needed to be done on Discourse here, but did not get a reply there. I might have a shot at adding it, thanks for the explanation.