Where to put supplementary docs?

[Robbin Ehn]

Hi, I agree.

I suggested co-located docs in some less public forums in the past.

One major challenge with the other places (CR, JBS, PR, wiki), is that
they don't handle versioning. (naturally)
This means the code can't safely refer to, e.g., a wiki page, as that
page may describe a newer version.
If a developer is working in JDK 11 or in the Loom project, they need
the relevant documentation for that specific fork/branch.

JBS/PR also have the issue that they primarily describe the original bug/patch.
The code integrated can change significantly during the PR's lifetime,
and one may need to read many comments in the PR/JBS to figure things
out.

Additionally, many developers 'grep' the code, which means co-located
documentation is very easy to find (and thus easier to keep up-to-date
or add new docs to).

A concrete example: https://wiki.openjdk.org/display/HotSpot/Synchronization
If you are hunting a bug in JDK 11, this page may be of value.
If you want to know how locking works in JDK 25, you shouldn't be
reading this page.

Co-locating the docs with the code helps with these issues.

/Robbin

On Thu, Apr 24, 2025 at 11:11 AM Andrew Haley
<aph-open at littlepinkcloud.com> wrote:
>
> Anyone?
>
> On 4/22/25 10:31, Andrew Haley wrote:
> > 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.
> >
>
> --
> Andrew Haley  (he/him)
> Java Platform Lead Engineer
> Red Hat UK Ltd. <https://www.redhat.com>
> https://keybase.io/andrewhaley
> EAC8 43EB D3EF DB98 CC77 2FAD A5CD 6035 332F A671
>