Kulla: JShell API ready for round two review

[Brian Goetz]

> So, you are saying you want:
>
>      JShell.create()
>
> as a convenience method for:
>
>      JShell.builder().build()

Yes.  I believe Paul asked for the same thing.

> Documenting the latter build approach as the standard way to create an
> instance exposes the builder without throwing it in there face.  Seem to
> me that adding that the one method call shorter approach makes thing
> more confusing: “so, do I use create() or builder()?!?".

This is a common enough pattern, and I don't think anyone will find it 
confusing if reasonably documented.  The issue with only being buildable 
through builders is one of "how many concepts do I have to learn to get 
started."  If there is a simple factory method that creates a useful 
form, then users can get started without having to learn about all the 
options that are possible during building.  Later, they can learn about 
additional options afforded by the builder.  (Also, users tend to get 
annoyed by overly-complicated paths to build something simple.)

> Should I stub it out so it is in the API now?

Good idea.

>> 6.  What is InternalDebugControl?  Will it eventually not be public?
>>  If it is to be public, consider moving its functionality to JShell.
>
> It is how internal debugging is turned on by the jshell tool.  Which is
> my main way of debugging the API.  I don’t want it public but the jshell
> tool is just a client of the API. Hence my question on how to hide it.
>   Sundar suggests non-exported class.

Would need to be a non-exported *package*.  Exports work at the package 
granularity.