groovy-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Paul King <pa...@asert.com.au>
Subject Re: incubator-groovy git commit: escape characters in javadoc and remove unnecessary @inheritdoc javadoc annotations
Date Fri, 13 Nov 2015 10:07:07 GMT
OK, I missed that capability altogether. Good to know. And I guess we
should make GroovyDoc mimic that behavior at some point too.

On Fri, Nov 13, 2015 at 6:16 AM, Pascal Schumacher
<pascalschumacher@gmx.net> wrote:
> 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