Modify rule S4123: move hint about JSdoc to exception, specifying tha…

…t it's about the @returns tag (#3582)

rules/S4123/javascript/rule.adoc

@@ -20,57 +20,45 @@ const x = Promise.resolve(42);
 await x;
 ----
 
-When running on JavaScript code, the JSdoc is prioritized over the type inference, so make sure that they are correct, using a `Promise<T>` type when needed.
+When calling a function that returns a promise as the last expression, you might forget to return it, especially if you refactored your code from a single-expression arrow function.
 
 [source,js,diff-id=2,diff-type=noncompliant]
 ----
-/**
- * @return {number}
- */
-async function foo() {
-  return await Promise.resolve(42);
+function foo() {
+  Promise.resolve(42);
 }
 async function bar() {
   await foo(); // Noncompliant
 }
 ----
 
-Either remove the JSdoc or fix it to correct the issue.
+Make sure that you return the promise.
 
 [source,js,diff-id=2,diff-type=compliant]
 ----
-/**
- * @return {Promise<number>}
- */
-async function foo() {
-  return await Promise.resolve(42);
-}
-async function bar() {
-  await foo();
-}
-----
-
-When calling a function that returns a promise as the last expression, you might forget to return it, especially if you refactored your code from a single-expression arrow function.
-
-[source,js,diff-id=3,diff-type=noncompliant]
-----
 function foo() {
-  Promise.resolve(42);
+  return Promise.resolve(42);
 }
 async function bar() {
-  await foo(); // Noncompliant
+  await foo(); // Compliant
 }
 ----
 
-Make sure that you return the promise.
+=== Exceptions
+
+The rule does not raise issues if you are awaiting a function whose definition contains JSdoc with `@returns` or `@return` tags. This is due to JSdoc often mistakenly declaring a returning type without mentioning that it is resolved by a promise. For example:
 
-[source,js,diff-id=3,diff-type=compliant]
+[source,js]
 ----
-function foo() {
-  return Promise.resolve(42);
+async function foo () {
+  await bar(); // Compliant
 }
-async function bar() {
-  await foo();
+
+/**
+ * @return {number}
+ */
+async function bar () {
+  return 42;
 }
 ----