Where to put supplementary docs?

[Dalibor Topic]

On 24/04/2025 11:10, Andrew Haley wrote:
> Anyone?

I assume that you've already selected against creating a 'supplementary 
documentation for individual changes' section on the wiki, right? I 
couldn't find it mentioned in the argument below.

cheers,
dalibor topic

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

-- 
<http://www.oracle.com> Dalibor Topic
Consulting Product Manager
Phone: +494089091214 <tel:+494089091214>, Mobile: +491737185961
<tel:+491737185961>

Oracle Global Services Germany GmbH
Hauptverwaltung: Riesstr. 25, D-80992 München
Registergericht: Amtsgericht München, HRB 246209
Geschäftsführer: Ralf Herrmann