REPL needs doc

[scabug]

REPL receives mention on the getting started page, but doesn't have a doc page of its own on the new scala-lang.org.

People have questions, REPL has answers.

[scabug]

Imported From: https://issues.scala-lang.org/browse/SI-7900?orig=1
Reporter: @som-snytt

[scabug]

@SethTisue said:
This would make a marvelous community contribution from a generous angelic individual.

[scabug]

@som-snytt said:
But to clarify, I bet the Scala folks would accept a contribution from the devil himself (or herself).

[scabug]

Hamish Dickson (hamish.dickson-at-gmail.com) said:
How detailed do you think we need this to be? We could probably write something of similar detail to the Getting Started page pretty quickly - or are you thinking of something more detailed?

[scabug]

@SethTisue said:
Even a page with just the basics would be really valuable, IMO.

Over time it would be nice if it eventually reached completeness, but it doesn't need to start there. A first version could end with a bullet list of things which exist but are not doc'ed (that, it seems like we could fairly easy get complete or nearly complete) and an invitation for further pull requests.

[scabug]

@som-snytt said:
Just a quick explanation would suffice, along the lines of "Missing doc is already fixed in [Ammonite|http://lihaoyi.github.io/Ammonite/]".

[scabug]

@SethTisue said:
TIL lastException:

scala> ???
scala.NotImplementedError: an implementation is missing
  at scala.Predef$.$qmark$qmark$qmark(Predef.scala:225)
  ... 33 elided

scala> lastException
res1: Throwable = scala.NotImplementedError: an implementation is missing

[scabug]

Hamish Dickson (hamish.dickson-at-gmail.com) said:
@seth - would you like this kind of detail in the REPL docs?

I started thinking about this doc last weekend - if either of you think it's helpful I'm happy to put a first draft into a gist this weekend so people can have a look and comment etc

[scabug]

@SethTisue said:
that'd be awesome! in the long run, we should have detailed doc that (yes) includes things like lastException. in the short run, anything is way better than nothing.

[scabug]

@som-snytt said:
I also got started, just to have a place to list features of interest.

scala/docs.scala-lang#476

I'm not able to build the pages yet, heads up.

[scabug]

@SethTisue said:
URL on the docs site is http://docs.scala-lang.org/overviews/repl/overview.html

leaving this ticket open in the hopes of attracting further contributors wanting to expand on the initial version.

[scabug]

Ches Martin (ches) said (edited on Jun 18, 2016 11:16:42 PM UTC):
Notes to self/other potential contributors:

• I've always wanted something to tell me more of what the mystical :power mode is about, when I might want to use it. I guess I'm not a power user!
• These 2.11 release notes would be a good source for fleshing out the overview more. A wealth of useful stuff there with a good start on docs for it already.
• The REPL has no config file but you can manually scala -i or use an alias or wrapper script to have your own library of utility functions, common imports, etc. The file can include REPL commands like :load and :paste.
• I'd like to know where to find properties that might be useful, e.g. scala -Dscala.color.

[scabug]

@som-snytt said:
More at scala/docs.scala-lang#726

[scabug]

@som-snytt said:
The overview page is seeded, and there's a page on programmatic invocation, i.e., what's the REPL API.