On Mon, 22 Nov 2021 17:43:08 GMT, Pavel Rappo <pra...@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
