RFR: 8276124: Provide snippet support for properties files [v2]

[Jonathan Gibbons]

On Mon, 22 Nov 2021 17:43:08 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/SnippetTaglet.java line 67:
>> 
>>> 65: public class SnippetTaglet extends BaseTaglet {
>>> 66: 
>>> 67:     public enum Language {
>> 
>> The idea of a `Language` object is good, but using an `enum` precludes easy extensibility.
>
> We'll figure out the extensibility when the need comes. The language of a snippet defines both the comment marker and the comment type. For now, an alternative to that enum would be a boolean flag, which is less readable.

All I'm suggesting is to make `Language` a class, with a public constructor and (for now) some standard static members.  In other words, plan for the possibility of additional languages, by not limiting the code to an enum at this time.

>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/snippet/Parser.java line 87:
>> 
>>> 85:         int payloadEnd();
>>> 86:         int markupStart();
>>> 87:     }
>> 
>> I'm surprised/disappointed that this may be necessary, although I accept there is a notable difference between "whole-line comments" and "end-of-line comments".  Is it possible to reduce `CoarseParser` down to a language-specific regular expression with named groups for the payload and markup, such that the regular expression could be  a property of the `Language` object?
>
> I'm going to answer both of your comments, this and that one above:
> 
>> I think you can simplify the code by reducing `CoarseParser` down to a language-specific regular expression with "standard" named groups for the payload and markup.
> 
> Regular expressions with named groups were the initial design. However, I changed it to `CoarseParser` halfway through the implementation, when saw how bulky the named regex were becoming. As you also note, "end-of-line comments" and "comment lines" differ. I couldn't quickly come up with a regex that accounts for both of them.

You may be somewhat missing the point I was trying to make.

You have two impls of `CoarseParser`, both of which contain a regular expression for the parsing, hidden inside their private matcher field.

The only other functionality of `CoarseParse` is `payloadEnd` and `markupStart`.

My suggestion is to start by updating each of the regex with named groups such that you can derive `payloadEnd` and `markupStart` from the appropriate named groups.

At that point, the only thing unique about the impls of `CoarseParser` is their regex, and that regex could become a property of the `Language` object.

> As you also note, "end-of-line comments" and "comment lines" differ. I couldn't quickly come up with a regex that accounts for both of them.

To be clear, I am _not_ suggesting a single regex.  I am suggesting a regex per supported language.

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

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