Where to put supplementary docs?

[Andrew Haley]

Sometimes, when reviewing a PR, we have supporting documents to
justify a change. These docs can include diagrams, etc. In the past
some such documents were put on the webrev server, and sometimes they
got lost. One example of such a file is "Fast Subtype Checking in the
HotSpot JVM," which explained the (now obsolete) secondary subtype
checking algorithm.

Today, documents are sometimes uploaded to JIRA or attached to the PR
itself. Sometimes they are stored in someone's personal web space, and
linked from a PR, and that's when things get lost.

It would be better for long-term retention if such documents were
included in the JDK repository itself, and committed to the repo as
part of the PR. I'm assuming that these files will be fairly small, so
will not greatly increase the size of the repo.

I propose to add a new subdirectory to jdk/doc, called "ref" or
"reference". This is not for every possible reference document, but
those that aid the maintainer and will be useful in the future. A
comment in the source code should refer the reader to the appropriate
reference document.

Does anyone here object to this? Is there some other place than
"doc/ref" that would be more appropriate?

Thanks,

Andrew.