Repository: netty/netty
Issue: should add java-doc for method DefaultPromise#cancel(boolean mayInterruptIfRunning)
Labels: documentation

### Expected behavior
implementation of method `io.netty.util.concurrent.DefaultPromise#cancel(boolean mayInterruptIfRunning)` actually ignored the param `mayInterruptIfRunning`.
so it need to make a comment like following:
(this comment is copied from `java.util.concurrent.CompletableFuture#cancel`):

>      * @param mayInterruptIfRunning this value has no effect in this
>      * implementation because interrupts are not used to control
>      * processing.
the other method `io.netty.util.concurrent.CompleteFuture#cancel` may do the same too.
### Actual behavior
there is no comment about the param `mayInterruptIfRunning`, which will make user confusing when call the `cancel` method with a param `mayInterruptIfRunning`.
### Netty version
4


Issue comments:
@laosijikaichele PRs welcome... that said I am not sure if we need anything here as `mayInterruptIfRunning` already signals that it may interrupt or not.
I am setting up the netty development environment, after that, I will try a PR for this doc issue. :)
Fixed by https://github.com/netty/netty/pull/7624

Pull request review comments:
at a minimum we need {@inheritDoc}, and in general I'm not convinced this change is necessary as the `cancel` operation itself is indicated as best effort in the original javadocs and therefore the parameter may not be used in general.
if a param value does not used in the method, then it should be indicated by the javadoc, but the original javadoc from `java.util.concurrent.Future#cancel` does not clearly indicate it, so the JVM team itself indicate it when the implementation method does not use the param `mayInterruptIfRunning`, please refer the javadoc of `java.util.concurrent.CompletableFuture#cancel` and `java.util.concurrent.ForkJoinTask#cancel` ;
 which javadocs clearly indicate that `mayInterruptIfRunning` has no effect in the implementation.
@laosijikaichele actually I think this is not correct as it just delegates it and if it is ignored or not depends on the implementation of `delegate`
@normanmaurer  agree,I deleted javadoc for this method.

Patch that resolved the issue:
diff --git a/common/src/main/java/io/netty/util/concurrent/CompleteFuture.java b/common/src/main/java/io/netty/util/concurrent/CompleteFuture.java
index 84376233dd3..ed5755f5727 100644
--- a/common/src/main/java/io/netty/util/concurrent/CompleteFuture.java
+++ b/common/src/main/java/io/netty/util/concurrent/CompleteFuture.java
@@ -140,6 +140,11 @@ public boolean isCancelled() {
         return false;
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * @param mayInterruptIfRunning this value has no effect in this implementation.
+     */
     @Override
     public boolean cancel(boolean mayInterruptIfRunning) {
         return false;
diff --git a/common/src/main/java/io/netty/util/concurrent/DefaultPromise.java b/common/src/main/java/io/netty/util/concurrent/DefaultPromise.java
index 6b175b2e5a0..dc595cfa99a 100644
--- a/common/src/main/java/io/netty/util/concurrent/DefaultPromise.java
+++ b/common/src/main/java/io/netty/util/concurrent/DefaultPromise.java
@@ -308,6 +308,11 @@ public V getNow() {
         return (V) result;
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * @param mayInterruptIfRunning this value has no effect in this implementation.
+     */
     @Override
     public boolean cancel(boolean mayInterruptIfRunning) {
         if (RESULT_UPDATER.compareAndSet(this, null, CANCELLATION_CAUSE_HOLDER)) {
diff --git a/common/src/main/java/io/netty/util/concurrent/ScheduledFutureTask.java b/common/src/main/java/io/netty/util/concurrent/ScheduledFutureTask.java
index 05cba6b83ad..6043d6ffec0 100644
--- a/common/src/main/java/io/netty/util/concurrent/ScheduledFutureTask.java
+++ b/common/src/main/java/io/netty/util/concurrent/ScheduledFutureTask.java
@@ -151,6 +151,11 @@ public void run() {
         }
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * @param mayInterruptIfRunning this value has no effect in this implementation.
+     */
     @Override
     public boolean cancel(boolean mayInterruptIfRunning) {
         boolean canceled = super.cancel(mayInterruptIfRunning);
diff --git a/transport/src/main/java/io/netty/channel/VoidChannelPromise.java b/transport/src/main/java/io/netty/channel/VoidChannelPromise.java
index be28f75db38..5aa61cd1332 100644
--- a/transport/src/main/java/io/netty/channel/VoidChannelPromise.java
+++ b/transport/src/main/java/io/netty/channel/VoidChannelPromise.java
@@ -166,6 +166,11 @@ public boolean tryFailure(Throwable cause) {
         return false;
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * @param mayInterruptIfRunning this value has no effect in this implementation.
+     */
     @Override
     public boolean cancel(boolean mayInterruptIfRunning) {
         return false;
diff --git a/transport/src/main/java/io/netty/channel/group/VoidChannelGroupFuture.java b/transport/src/main/java/io/netty/channel/group/VoidChannelGroupFuture.java
index e8fa84266b4..740ac337022 100644
--- a/transport/src/main/java/io/netty/channel/group/VoidChannelGroupFuture.java
+++ b/transport/src/main/java/io/netty/channel/group/VoidChannelGroupFuture.java
@@ -138,6 +138,11 @@ public Void getNow() {
         return null;
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * @param mayInterruptIfRunning this value has no effect in this implementation.
+     */
     @Override
     public boolean cancel(boolean mayInterruptIfRunning) {
         return false;


Test patch: