groovy-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Pascal Schumacher <pascalschumac...@gmx.net>
Subject Re: incubator-groovy git commit: escape characters in javadoc and remove unnecessary @inheritdoc javadoc annotations
Date Thu, 12 Nov 2015 20:16:54 GMT
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);
>>


Mime
View raw message