RFR: 8322708: Global HTML attributes are not allowed [v3]
Jonathan Gibbons
jjg at openjdk.org
Fri Jun 14 12:15:48 UTC 2024
On Tue, 11 Jun 2024 22:12:42 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:
>> Nizar Benalla has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains ten additional commits since the last revision:
>>
>> - Null safety
>> - Merge branch 'master' into html-attributes
>> - remove trailing whitespace
>> - -Add a boolean attribute to the enum type
>> -Simply regex in `visitAttribute`
>> -Simplified the Test
>> -Added a negative test
>> - no longer print summary
>> - no longer print summary
>> - Add small comment
>> - Remove classpath exception
>> - Allow global variables
>
> test/langtools/jdk/javadoc/doclet/TestGlobalHtml/pkg1/C1.java line 1:
>
>> 1: /*
>
> This example is way too big and/or insufficiently focused on global attributes. As an example of this, compare the size of the input programs to the size (number) of strings given to `checkOutput` in. the previous file.
>
> The challenge of writing good tests is to find the simplest example that causes the newly-written code to be executed.
>
> Also, while not wrong, it's also "old-school" to write separate classes in separate files to run through `javadoc`. You can often come up with small enough examples to fit in text blocks in the main test program.
>
> In this case, I would suggest providing a class with a comment containing a whole bunch of simple tags each containing one or more global attributes. It doesn't have to make "sense" as a comment -- it just has to exercise code paths in the new code.
Also, consider what it might mean to write "negative" tests. That might be a bit tricky, given these are global attributes, accepted on all HTML tags that can appear in a doc comment, so at least make sure there is a test (there may already be a test) for something that is not a global attribute, just to test the error reporting.
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/19652#discussion_r1635550821
More information about the javadoc-dev
mailing list