<div dir="ltr"><div dir="ltr">On Tue, Apr 22, 2025 at 4:31 AM Andrew Haley <<a href="mailto:aph-open@littlepinkcloud.com">aph-open@littlepinkcloud.com</a>> wrote:</div><div class="gmail_quote gmail_quote_container"><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">I propose to add a new subdirectory to jdk/doc, called "ref" or<br>
"reference". This is not for every possible reference document, but<br>
those that aid the maintainer and will be useful in the future. A<br>
comment in the source code should refer the reader to the appropriate<br>
reference document.</blockquote><div><br></div><div>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.</div><div><br></div><div>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<span style="font-family:monospace"> /* REFERENCE DOCUMENTATION HERE: <location> KEEP UP TO DATE */ </span>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.</div><div><br></div><div>-Archie</div><div> </div></div><span class="gmail_signature_prefix">-- </span><br><div dir="ltr" class="gmail_signature">Archie L. Cobbs<br></div></div>