Essentially, all the abstractions need more explanatory class documentation (this is probably already on your list.) The comments here are mostly examples rather than an exhaustive list, but the key theme is, as the docs stand now, they don't really help you enough to understand the key abstractions and their relationships.

Javadoc serves multiple purposes; one under-served purpose is to guide readers towards the right abstraction. Its common that someone will land on a page for a subordinate abstraction (e.g., you find the page for JDBC ResultSet, but it says nothing that tells you how you *get* a ResultSet, so it doesn't help lead you to Connection, which is where you want to start.)

Package doc. There's no package doc; this is a great place to provide a big-picture descriptive overview, illustrate the concepts, give examples, etc. This should prominently point to JShell as the main abstraction here.

JShell. Needs class doc explaining the conversational state model, how stuff gets into (eval) and out of (keys, events, accessor methods) JShell, that to get a JShell you call create(), etc. Explain what a Snippet is. Explain the threading issues. Explain the snippet lifecycle (and point to Key.Status.)

JShell.eval. Should say that the resulting events are both returned *and* broadcast to all listeners. The business about public/private/etc probably belongs somewhere else -- where you define the kinds of snippets. This could go well in the package doc.

SourceCodeAnalysis. Explain the role of source code analysis in the JShell story; this is useful for some clients and can be ignored for others.

Key. Key explains what it is, but not what Snippet is. Somewhere, you have to explain what a snippet is, what kinds of snippets there are (ref to Key.Kind), etc.

Key.Status. This is so important. Make it clear that status for key k1 can change due to changes to k2.

Key.SubKind. Should differentiate between Kind and SubKind in the Kind docs; give an example of why a key's Kind is constant but its SubKind might change over time.

KeyStatusEvent. Tell us why we are interested in these events, and how they are communicated (return status, event listeners.)

UnresolvedException (naming.) Should either be UnresolvedXxxException or KeyResolutionException or something like that.

EvalException. Do we need this? Why not just use some existing exception type (ExecutionException?) and call getCause() on it to get the exception class?

-Brian

Hi Robert,

There doesn't seem to be a package-info.java file for the new package.

Some of the types reference particular sections of "The Java Language Specification." In the JDK sources, we use the @jls tag for that purpose. There are example uses of the tag in the java.lang package.

The use of fields rather than methods in KeyStatusEvent is not advised.

HTH,

-Joe

JShell construction
--

There is one creation method:

public static JShell create(InputStream in, PrintStream out, PrintStream err)

But i dunno what it does with "in", "out, or "err". If i wanted to write my own jshell tool how would i use this to trigger reading from "in”?

If so and if possible concisely it might be useful to have a simple and dumb example in the JavaDoc.

>
> What are the constraints for "previousStatus" and "status". I presume "previousStatus" can be of all Key.Status values, including NONEXISTENT, where as "status" can be anything but NONEXISTENT?

Yes

>
> If "isSignatureChange" is true does that mean "key" is an instance of DeclarationKey?

Yes

>
> If "isSignatureChange" is true is there a way to obtain the old signature?

Cache it

>
> Is there any meaningful relationship between the types of causeKey and key?


So basically for a kind of say TYPE_DECL the set of sub-kinds are {CLASS_SUBKIND, INTERFACE_SUBKIND, INTERFACE_SUBKIND} and such a snippet can transform from one to another one in that set.

I had to look at the code to get a better idea of the classifications. I found that easier than drilling down to the enum constant detail section of the JavaDoc. So perhaps some table would be useful at the top-level enum doc.

-Paul (extracted)