Mailing-List: contact dev-help@groovy.incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@groovy.incubator.apache.org
Subject: Re: incubator-groovy git commit: escape characters in javadoc and
 remove unnecessary @inheritdoc javadoc annotations
To: dev@groovy.incubator.apache.org
References: <a612e816c4f44c9a877f6fdf1f9cdab0@git.apache.org>
 <CAMbkE7ScYQ+cErhZhnUdVJ3sqbALDLtF=OLRD+7WepKKkjw2rQ@mail.gmail.com>
From: Pascal Schumacher <pascalschumacher@gmx.net>
Message-ID: <5644F3B6.4050109@gmx.net>
Date: Thu, 12 Nov 2015 21:16:54 +0100
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:38.0) Gecko/20100101
 Thunderbird/38.3.0
MIME-Version: 1.0
In-Reply-To: 
 <CAMbkE7ScYQ+cErhZhnUdVJ3sqbALDLtF=OLRD+7WepKKkjw2rQ@mail.gmail.com>
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Transfer-Encoding: 7bit

Using:

/**
   * {@inheritDoc}
   */

should never be necessary, because:

 >The Javadoc tool has the ability to copy or "inherit" method comments 
in classes and interfaces under the following two circumstances. 
Constructors, fields and nested classes do not inherit doc comments.
 >
 >Automatically inherit comment to fill in missing text - When a main 
description, or @return, @param or @throws tag is missing from a method 
comment, the Javadoc tool copies the corresponding main description or 
 >tag comment from the method it overrides or implements (if any), 
according to the algorithm below.

https://docs.oracle.com/javase/6/docs/technotes/tools/solaris/javadoc.html 
"Automatic Copying of Method Comments"

Or I'm I missing something?

Am 12.11.2015 um 21:06 schrieb Paul King:
> When you say "unnecessary", do you mean currently not supported by GroovyDoc?
> Won't the info go missing from:
> http://docs.groovy-lang.org/latest/html/api/groovy/lang/ObjectRange.html
> And also be missing in the gapi once we fix:
> https://issues.apache.org/jira/browse/GROOVY-3782
>
> Or am I missing something?
>
>
> On Fri, Nov 13, 2015 at 5:57 AM,  <pascalschumacher@apache.org> wrote:
>> Repository: incubator-groovy
>> Updated Branches:
>>    refs/heads/master 3001ba559 -> 459638b0e
>>
>>
>> escape characters in javadoc and remove unnecessary @inheritdoc javadoc annotations
>>
>>
>> Project: http://git-wip-us.apache.org/repos/asf/incubator-groovy/repo
>> Commit: http://git-wip-us.apache.org/repos/asf/incubator-groovy/commit/459638b0
>> Tree: http://git-wip-us.apache.org/repos/asf/incubator-groovy/tree/459638b0
>> Diff: http://git-wip-us.apache.org/repos/asf/incubator-groovy/diff/459638b0
>>
>> Branch: refs/heads/master
>> Commit: 459638b0e65e8974b25ff7584c35aaf183dcce7f
>> Parents: 3001ba5
>> Author: pascalschumacher <pascalschumacher@gmx.net>
>> Authored: Thu Nov 12 20:56:43 2015 +0100
>> Committer: pascalschumacher <pascalschumacher@gmx.net>
>> Committed: Thu Nov 12 20:56:43 2015 +0100
>>
>> ----------------------------------------------------------------------
>>   src/main/groovy/lang/ObjectRange.java | 38 +-----------------------------
>>   1 file changed, 1 insertion(+), 37 deletions(-)
>> ----------------------------------------------------------------------
>>
>>
>> http://git-wip-us.apache.org/repos/asf/incubator-groovy/blob/459638b0/src/main/groovy/lang/ObjectRange.java
>> ----------------------------------------------------------------------
>> diff --git a/src/main/groovy/lang/ObjectRange.java b/src/main/groovy/lang/ObjectRange.java
>> index 30c8e43..d328631 100644
>> --- a/src/main/groovy/lang/ObjectRange.java
>> +++ b/src/main/groovy/lang/ObjectRange.java
>> @@ -71,7 +71,7 @@ public class ObjectRange extends AbstractList implements Range {
>>       }
>>
>>       /**
>> -     * Creates a new {@link ObjectRange} assumes smaller <= larger, else behavior is undefined.
>> +     * Creates a new {@link ObjectRange} assumes smaller &lt;&#61; larger, else behavior is undefined.
>>        * Caution: Prefer the other constructor when in doubt.
>>        *
>>        * Optimized Constructor avoiding initial computation of comparison.
>> @@ -167,9 +167,6 @@ public class ObjectRange extends AbstractList implements Range {
>>           }
>>       }
>>
>> -    /**
>> -     * {@inheritDoc}
>> -     */
>>       public boolean equals(Object that) {
>>           return (that instanceof ObjectRange) ? equals((ObjectRange) that) : super.equals(that);
>>       }
>> @@ -187,30 +184,18 @@ public class ObjectRange extends AbstractList implements Range {
>>                   && DefaultTypeTransformation.compareEqual(this.to, that.to);
>>       }
>>
>> -    /**
>> -     * {@inheritDoc}
>> -     */
>>       public Comparable getFrom() {
>>           return from;
>>       }
>>
>> -    /**
>> -     * {@inheritDoc}
>> -     */
>>       public Comparable getTo() {
>>           return to;
>>       }
>>
>> -    /**
>> -     * {@inheritDoc}
>> -     */
>>       public boolean isReverse() {
>>           return reverse;
>>       }
>>
>> -    /**
>> -     * {@inheritDoc}
>> -     */
>>       public Object get(int index) {
>>           if (index < 0) {
>>               throw new IndexOutOfBoundsException("Index: " + index + " should not be negative");
>> @@ -234,9 +219,6 @@ public class ObjectRange extends AbstractList implements Range {
>>           return value;
>>       }
>>
>> -    /**
>> -     * {@inheritDoc}
>> -     */
>>       public Iterator iterator() {
>>           return new Iterator() {
>>               private int index;
>> @@ -292,9 +274,6 @@ public class ObjectRange extends AbstractList implements Range {
>>           throw new UnsupportedOperationException("size must not be changed");
>>       }
>>
>> -    /**
>> -     * {@inheritDoc}
>> -     */
>>       public int size() {
>>           if (size == -1) {
>>               if ((from instanceof Integer || from instanceof Long)
>> @@ -330,9 +309,6 @@ public class ObjectRange extends AbstractList implements Range {
>>           return size;
>>       }
>>
>> -    /**
>> -     * {@inheritDoc}
>> -     */
>>       public List subList(int fromIndex, int toIndex) {
>>           if (fromIndex < 0) {
>>               throw new IndexOutOfBoundsException("fromIndex = " + fromIndex);
>> @@ -350,16 +326,10 @@ public class ObjectRange extends AbstractList implements Range {
>>           return new ObjectRange((Comparable) get(fromIndex), (Comparable) get(--toIndex), reverse);
>>       }
>>
>> -    /**
>> -     * {@inheritDoc}
>> -     */
>>       public String toString() {
>>           return reverse ? "" + to + ".." + from : "" + from + ".." + to;
>>       }
>>
>> -    /**
>> -     * {@inheritDoc}
>> -     */
>>       public String inspect() {
>>           String toText = InvokerHelper.inspect(to);
>>           String fromText = InvokerHelper.inspect(from);
>> @@ -383,9 +353,6 @@ public class ObjectRange extends AbstractList implements Range {
>>           return false;
>>       }
>>
>> -    /**
>> -     * {@inheritDoc}
>> -     */
>>       public void step(int step, Closure closure) {
>>           if (step == 0) {
>>               if (compareTo(from, to) != 0) {
>> @@ -422,9 +389,6 @@ public class ObjectRange extends AbstractList implements Range {
>>           }
>>       }
>>
>> -    /**
>> -     * {@inheritDoc}
>> -     */
>>       public List step(int step) {
>>           IteratorClosureAdapter adapter = new IteratorClosureAdapter(this);
>>           step(step, adapter);
>>