Where to put supplementary docs?

[Archie Cobbs]

On Tue, Apr 22, 2025 at 4:31 AM Andrew Haley <aph-open at littlepinkcloud.com>
wrote:

> 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.


I support this idea. I'm sure in lots of other places too, but in the
compiler, there is often subtle or non-obvious logic happening that could
benefit from a more proper explanation than what you get from inline
comments, etc.

The hard part is keeping this documentation up-to-date as the code evolves.
If the docs are not sitting in the same directory as the code they
document, then there probably needs to be some other trick to remind people
to keep them in sync e.g., a big comment at the top of the file like /*
REFERENCE DOCUMENTATION HERE: <location> KEEP UP TO DATE */ or something.
Even better, add a skara check that mechanically verifies, for any change
to a source file, either (a) there is no corresponding reference
documentation or (b) that documentation has been updated (perhaps with just
a trivial date/counter bump if no real change was needed), etc. Then the
documentation updates would be naturally included as part of PR reviews.

-Archie

-- 
Archie L. Cobbs
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/jdk-dev/attachments/20250422/8db7cf0b/attachment.htm>