RFR: JDK-8190417 java.util.regex.Matcher method doc points to incorrect links

[David Holmes]

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>
> 
> 
>