A little suggestion to ease understanding for newcomers even more... (Re: The State of the Module System: Automatic Edition

[Rony G. Flatscher]

Mark,

the document is really very informative and helpful, very well done!

Having lurked for quite some time at the fence of this (and the jdk9-dev) e-mail list there are
quite a few terms, concepts that occur in the discussions, but which are either not mentioned at all
or might need a little bit of further explanation in the document in order to ease the understanding
for newcomers to the module system.

Maybe adding a little "terms" addendum section at the end of the document for the following terms
(some are explained in the document's main body already, however a brief explanation in the
suggested terms addendum might be helpful in addition, maybe with a link to the section in the
document where e.g. "automatic module" gets explained in detail) might ease newcomers the
understanding of some of these e-mail discussions:

  * "adding a read edge" (why, how?)
  * "automatic module" (what is it?)
  * classloaders: which classloaders load what from where and why?
      o "bootstrap, extension, endorsed mechanisms" (brief purpose; gone? replaced by?)
      o  "module upgrade path mechanism" (why, how?)
  * "layer API" (why, what do they allow for?)
  * "modulepath vs. classpath" (brief implications)
  * "observable" (what is it?)
  * "split package" (why, what is it?)
  * "unnamed module" (what is it?)
  * "upgradable modules" (why, what are they?)

Please note, that these suggestions are meant to ease *newcomers* to understand these terms that get
used in the various discussions not the experienced experts in this mailing group.

    [Maybe a clue/hint to the terms and relationships to each other for the terms "jdk9/dev" and
    "jigsaw/jake" would be helpful too for newcomers, who may feel lost by not being able to
    understand the terms and what they stand for immediately. As everyone in this list knows about
    them there are no clues given in the e-mail discussions about them and where to find them, hence
    difficult to understand/relate to for newcomers.]

It would be great, if a single document would contain and explain all information relating to the
new module system, hence suggesting such an addendum (appendix) section to the current document.

---rony

P.S.: Another idea would be to add another (appendix) section at the end of the document that
explains all the new "javac" and "java" switches introduced for the module system (problem and
sytnax that each new switch helps solve). Again, it would probably suffice to give brief
explanations, definitions (what module related problems can be solved with which switch).



On 08.03.2016 17:47, mark.reinhold at oracle.com wrote:
> I've posted an update to the State of the Module System document [1].
>
> The main change in this edition is the introduction of material on
> compatibility and migration, including automatic modules [2].  This
> update also revises the description of reflective readability [3],
> reorders the text to improve the flow of the narrative, and is
> organized into a two-level hierarchy of sections and subsections
> for easier navigation.
>
> Comments and discussion are welcome here on jigsaw-dev but, as usual,
> the best way to ensure that the EG sees any specific comment is to
> send it to the EG's "suggestion box" list, jpms-spec-comments [4].
>
> - Mark
>
>
> [1] http://openjdk.java.net/projects/jigsaw/spec/sotms/
> [2] http://openjdk.java.net/projects/jigsaw/spec/sotms/#compatibility--migration
> [3] http://openjdk.java.net/projects/jigsaw/spec/sotms/#reflective-readability
> [4] http://mail.openjdk.java.net/mailman/listinfo/jpms-spec-comments