RFR: JDK-8190417 java.util.regex.Matcher method doc points to incorrect links
Michal Vala
mvala at redhat.com
Thu May 31 10:09:57 UTC 2018
Hi Lance, David,
I've found few more javadoc line length issues, so I've fixed that.
Regarding to linking methods, I guess all links should have arguments. Now when
I link `#appendTail`, it goes to first instance, which is
appendTail(StringBuffer). So it should be explicit everywhere, Right? Should I
fix them all under this jbs id ?
On 05/31/2018 04:32 AM, David Holmes wrote:
> Hi Lance, Michal,
>
> When I looked into javadoc rules last week it seemed that links to methods
> should include the () if no-args ie.
>
> + * {@link #find find} methods.
>
> should be
>
> + * {@link #find() find} methods.
>
> Of course now I can't find those rules! The javadoc guide [1] doesn't seem to
> include or refer to a tag reference!
>
> Cheers,
> David
>
> [1] https://docs.oracle.com/javase/10/javadoc/toc.htm
>
> On 31/05/2018 3:28 AM, Lance Andersen wrote:
>> Hi Michal,
>>
>> I made a couple of additional minor tweaks
>>
>> - Cleaned the line length in a couple of places
>> - Addressed an inconsistency where Matcher’s was used in place of matcher’s
>> (which is used everywhere else in the javadoc)
>>
>> Here is the updated diff:
>>
>> ——————————
>> $ hg diff src/java.base/share/classes/java/util/regex/Matcher.java
>> diff -r 3195a713e24d src/java.base/share/classes/java/util/regex/Matcher.java
>> --- a/src/java.base/share/classes/java/util/regex/Matcher.java Mon May 21
>> 23:40:52 2018 +0000
>> +++ b/src/java.base/share/classes/java/util/regex/Matcher.java Wed May 30
>> 13:25:50 2018 -0400
>> @@ -1,5 +1,5 @@
>> /*
>> - * Copyright (c) 1999, 2015, Oracle and/or its affiliates. All rights reserved.
>> + * Copyright (c) 1999, 2018, Oracle and/or its affiliates. All rights reserved.
>> * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
>> *
>> * This code is free software; you can redistribute it and/or modify it
>> @@ -586,8 +586,8 @@
>> *
>> * <p> For a matcher <i>m</i> with input sequence <i>s</i>,
>> * the expressions <i>m.</i>{@code group()} and
>> - * <i>s.</i>{@code substring(}<i>m.</i>{@code
>> start(),} <i>m.</i>{@code end())}
>> - * are equivalent. </p>
>> + * <i>s.</i>{@code substring(}<i>m.</i>{@code start(),} <i>m.</i>
>> + * {@code end())} are equivalent. </p>
>> *
>> * <p> Note that some patterns, for example {@code a*}, match the empty
>> * string. This method will return the empty string when the pattern
>> @@ -959,9 +959,9 @@
>> * string.
>> *
>> * <p> This method is intended to be used in a loop together with the
>> - * {@link #appendTail appendTail} and {@link #find find} methods. The
>> - * following code, for example, writes {@code one dog two dogs in the
>> - * yard} to the standard-output stream: </p>
>> + * {@link #appendTail(java.lang.StringBuilder) appendTail} and
>> + * {@link #find find} methods. The following code, for example, writes
>> + * {@code one dog two dogs in the yard} to the standard-output stream: </p>
>> *
>> * <blockquote><pre>
>> * Pattern p = Pattern.compile("cat");
>> @@ -1123,8 +1123,9 @@
>> * <p> This method reads characters from the input sequence, starting at
>> * the append position, and appends them to the given string builder.
>> It is
>> * intended to be invoked after one or more invocations of the {@link
>> - * #appendReplacement appendReplacement} method in order to copy the
>> - * remainder of the input sequence. </p>
>> + * #appendReplacement(java.lang.StringBuilder,java.lang.String)
>> + * appendReplacement} method in order to copy the remainder of the input
>> + * sequence. </p>
>> *
>> * @param sb
>> * The target string builder
>> @@ -1770,18 +1771,18 @@
>> }
>> /**
>> - * Generates a String from this Matcher's input in the specified range.
>> + * Generates a String from this matcher's input in the specified range.
>> *
>> * @param beginIndex the beginning index, inclusive
>> * @param endIndex the ending index, exclusive
>> - * @return A String generated from this Matcher's input
>> + * @return A String generated from this matcher's input
>> */
>> CharSequence getSubSequence(int beginIndex, int endIndex) {
>> return text.subSequence(beginIndex, endIndex);
>> }
>> /**
>> - * Returns this Matcher's input character at index i.
>> + * Returns this matcher's input character at index i.
>> *
>> * @return A char from the specified index
>> */
>>
>> -----------------------------
>>> On May 30, 2018, at 11:10 AM, Michal Vala <mvala at redhat.com> wrote:
>>>
>>> Hi Lance,
>>>
>>> thanks, I'd appreciate that
>>>
>>> On 05/30/2018 04:32 PM, Lance Andersen wrote:
>>>> I can sponsor this for you
>>>>> On May 30, 2018, at 7:17 AM, Michal Vala <mvala at redhat.com> wrote:
>>>>>
>>>>> Hi,
>>>>>
>>>>> please review and eventually sponsor this small doc patch fixing method
>>>>> links in java.util.regex.Matcher
>>>>>
>>>>> webrev: http://cr.openjdk.java.net/~mvala/jdk/jdk/JDK-8190417/webrev.00/
>>>>>
>>>>> Thanks!
>>>>>
>>>>> --
>>>>> Michal Vala
>>>>> OpenJDK QE
>>>>> Red Hat Czech
>>>> <http://oracle.com/us/design/oracle-email-sig-198324.gif>
>>>> <http://oracle.com/us/design/oracle-email-sig-198324.gif>
>>>> <http://oracle.com/us/design/oracle-email-sig-198324.gif>
>>>> <http://oracle.com/us/design/oracle-email-sig-198324.gif>Lance Andersen|
>>>> Principal Member of Technical Staff | +1.781.442.2037
>>>> Oracle Java Engineering
>>>> 1 Network Drive
>>>> Burlington, MA 01803
>>>> Lance.Andersen at oracle.com <mailto:Lance.Andersen at oracle.com>
>>>
>>> --
>>> Michal Vala
>>> OpenJDK QE
>>> Red Hat Czech
>>
>> <http://oracle.com/us/design/oracle-email-sig-198324.gif>
>> <http://oracle.com/us/design/oracle-email-sig-198324.gif>
>> <http://oracle.com/us/design/oracle-email-sig-198324.gif>
>> <http://oracle.com/us/design/oracle-email-sig-198324.gif>Lance Andersen|
>> Principal Member of Technical Staff | +1.781.442.2037
>> Oracle Java Engineering
>> 1 Network Drive
>> Burlington, MA 01803
>> Lance.Andersen at oracle.com <mailto:Lance.Andersen at oracle.com>
>>
>>
>>
--
Michal Vala
OpenJDK QE
Red Hat Czech
More information about the core-libs-dev
mailing list