RFR: 8273544: Increase test coverage for snippets [v2]

[Pavel Rappo]

On Thu, 18 Nov 2021 17:37:16 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Pavel Rappo has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Test one more corner case example
>
> test/langtools/jdk/javadoc/doclet/testSnippetTag/TestSnippetMarkup.java line 185:
> 
>> 183:                                 link(First) link(line)
>> 184:                                   Second line
>> 185:                                 """, "link\\((.+?)\\)", r -> link(true, "java.lang.Object#Object", r.group(1)))
> 
> clever

Thanks. It is mainly for readability, to clearly show how the `@link` is expected to work. That said, the construct is somewhat clumsy. I hope to improve it, once templated strings arrive (https://openjdk.java.net/jeps/8273943).

> test/langtools/jdk/javadoc/doclet/testSnippetTag/TestSnippetMarkup.java line 388:
> 
>> 386:         // generate documentation at low cost and do not interfere with the
>> 387:         // calling test state; for that, do not create file trees, do not write
>> 388:         // to std out/err, and generally try to keep everything in memory
> 
> I understand what you're doing here, but I'm surprised you need to go to the trouble of a separate run of javadoc to get the link output.   Can you not put the link tag and the link markup tag in the same source, and then extract the two `<a>` from the generated file?   Maybe put distinguishing characters around each instance, to make locating them easier.  For example:
> 
> 
>  /**
>   * First sentence.  TAG {@link Object} TAG.
>   * {@snippet :
>   *      MARKUP Object MARKUP // @link substring=Object target=Object
>   * }
>   */

What you suggested is how I had that initially. But then a test purist in me demanded a clear way of getting the link without interfering with the test logic.

As for text blocks: to me, indenting a text block is a complex, subjective and unsettled issue. I would postpone re-indenting them for now, primarily because of the churn it would otherwise introduce to the dependent PRs. 

If neither of these issues is a showstopper, I would really like to integrate this PR to unlock more urgent work on the snippets feature before RDP 1, which is on 2021/12/09 as per the Schedule at https://openjdk.java.net/projects/jdk/18/. Sometime after this PR is integrated, we can revisit this.

> test/langtools/jdk/javadoc/doclet/testSnippetTag/TestSnippetPathOption.java line 168:
> 
>> 166:      */
>> 167:     @Test
>> 168:     public void testSearchPath(Path base) throws Exception {
> 
> Not wrong, but arguably somewhat superfluous. This is close to being a file manager test, not a snippet test.

I can add a comment that this test is a part of an end-to-end demonstration of how --snippet-path should work. This is a black-box test that assumes nothing about the implementation of the feature.

-------------

PR: https://git.openjdk.java.net/jdk/pull/6359