This is an automated email from the ASF dual-hosted git repository.
asf-gitbox-commits pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/groovy.git
The following commit(s) were added to refs/heads/master by this push:
new fa4d228fb1 Tweak groovydoc
fa4d228fb1 is described below
commit fa4d228fb1f8f1acefa0f21e47096e8ffe332e54
Author: Daniel Sun <[email protected]>
AuthorDate: Sat May 23 03:38:08 2026 +0900
Tweak groovydoc
---
src/main/groovy/groovy/beans/ListenerList.groovy | 4 +++
.../beans/ListenerListASTTransformation.groovy | 32 ++++++++++++++++++++++
.../groovy/cli/internal/CliBuilderInternal.groovy | 12 ++++++++
src/main/groovy/groovy/concurrent/Dataflows.groovy | 9 ++++++
src/main/groovy/groovy/grape/GrapeUtil.groovy | 3 ++
.../groovy/transform/ConditionalInterrupt.groovy | 11 +++++++-
src/main/groovy/groovy/transform/Immutable.groovy | 18 ++++++++++--
.../groovy/groovy/transform/ThreadInterrupt.groovy | 6 ++++
.../groovy/groovy/transform/TimedInterrupt.groovy | 15 ++++++++--
src/main/groovy/groovy/util/ConfigSlurper.groovy | 9 +++++-
src/main/groovy/groovy/util/FileTreeBuilder.groovy | 2 +-
11 files changed, 113 insertions(+), 8 deletions(-)
diff --git a/src/main/groovy/groovy/beans/ListenerList.groovy
b/src/main/groovy/groovy/beans/ListenerList.groovy
index 12bd26b117..bdf02c6240 100644
--- a/src/main/groovy/groovy/beans/ListenerList.groovy
+++ b/src/main/groovy/groovy/beans/ListenerList.groovy
@@ -127,11 +127,15 @@ import java.lang.annotation.Target
* A suffix for creating the add, remove, and get methods
* defaulting to the name of the listener type, e.g. if name is set to
MyListener,
* then the class will have addMyListener, removeMyListener, and
getMyListeners methods.
+ *
+ * @return the suffix used when deriving generated listener method names
*/
String name() default ''
/**
* Whether or not the methods created should be synchronized at the method
level.
+ *
+ * @return {@code true} if generated listener methods should be
synchronized
*/
boolean synchronize() default false
}
diff --git a/src/main/groovy/groovy/beans/ListenerListASTTransformation.groovy
b/src/main/groovy/groovy/beans/ListenerListASTTransformation.groovy
index 5c9a6277cd..7644f91b19 100644
--- a/src/main/groovy/groovy/beans/ListenerListASTTransformation.groovy
+++ b/src/main/groovy/groovy/beans/ListenerListASTTransformation.groovy
@@ -147,6 +147,14 @@ class ListenerListASTTransformation implements
ASTTransformation, Opcodes {
* ${field.name}.add(listener)
* }
* </pre>
+ *
+ * @param source the current source unit
+ * @param node the {@code @ListenerList} annotation node
+ * @param declaringClass the class receiving the generated method
+ * @param field the annotated listener list field
+ * @param listener the listener type
+ * @param name the logical listener name used in generated method names
+ * @param synchronize {@code true} if the generated method should be
synchronized
*/
void addAddListener(SourceUnit source, AnnotationNode node, ClassNode
declaringClass, FieldNode field, ClassNode listener, String name, synchronize) {
@@ -188,6 +196,14 @@ class ListenerListASTTransformation implements
ASTTransformation, Opcodes {
* ${field.name}.remove(listener)
* }
* </pre>
+ *
+ * @param source the current source unit
+ * @param node the {@code @ListenerList} annotation node
+ * @param declaringClass the class receiving the generated method
+ * @param field the annotated listener list field
+ * @param listener the listener type
+ * @param name the logical listener name used in generated method names
+ * @param synchronize {@code true} if the generated method should be
synchronized
*/
void addRemoveListener(SourceUnit source, AnnotationNode node, ClassNode
declaringClass, FieldNode field, ClassNode listener, String name, synchronize) {
def methodModifiers = synchronize ? ACC_PUBLIC | ACC_SYNCHRONIZED :
ACC_PUBLIC
@@ -227,6 +243,14 @@ class ListenerListASTTransformation implements
ASTTransformation, Opcodes {
* return __result as ${name.capitalize}[]
* }
* </pre>
+ *
+ * @param source the current source unit
+ * @param node the {@code @ListenerList} annotation node
+ * @param declaringClass the class receiving the generated method
+ * @param field the annotated listener list field
+ * @param listener the listener type
+ * @param name the logical listener name used in generated method names
+ * @param synchronize {@code true} if the generated method should be
synchronized
*/
void addGetListeners(SourceUnit source, AnnotationNode node, ClassNode
declaringClass, FieldNode field, ClassNode listener, String name, synchronize) {
def methodModifiers = synchronize ? ACC_PUBLIC | ACC_SYNCHRONIZED :
ACC_PUBLIC
@@ -263,6 +287,14 @@ class ListenerListASTTransformation implements
ASTTransformation, Opcodes {
* }
* }
* </pre>
+ *
+ * @param source the current source unit
+ * @param node the {@code @ListenerList} annotation node
+ * @param declaringClass the class receiving the generated methods
+ * @param field the annotated listener list field
+ * @param types the generic listener list types
+ * @param synchronize {@code true} if generated fire methods should be
synchronized
+ * @param method the listener callback method used to derive the fire
method
*/
void addFireMethods(SourceUnit source, AnnotationNode node, ClassNode
declaringClass, FieldNode field, GenericsType[] types, boolean synchronize,
MethodNode method) {
diff --git a/src/main/groovy/groovy/cli/internal/CliBuilderInternal.groovy
b/src/main/groovy/groovy/cli/internal/CliBuilderInternal.groovy
index a20555f5a1..554295e8c0 100644
--- a/src/main/groovy/groovy/cli/internal/CliBuilderInternal.groovy
+++ b/src/main/groovy/groovy/cli/internal/CliBuilderInternal.groovy
@@ -249,6 +249,10 @@ class CliBuilderInternal {
/**
* Internal method: Detect option specification method calls.
+ *
+ * @param name the invoked option name
+ * @param args the invocation arguments
+ * @return the generated option handle, or the delegated meta-class result
*/
def invokeMethod(String name, Object args) {
if (args instanceof Object[]) {
@@ -305,6 +309,9 @@ class CliBuilderInternal {
/**
* Make options accessible from command line args with parser.
* Returns null on bad command lines after displaying usage message.
+ *
+ * @param args the command line arguments to parse
+ * @return the parsed option accessor, or {@code null} if parsing fails
*/
OptionAccessor parse(args) {
CommandLine commandLine = createCommandLine()
@@ -354,6 +361,11 @@ class CliBuilderInternal {
// implementation details -------------------------------------
/**
* Internal method: How to create an OptionSpec from the specification.
+ *
+ * @param shortname the short option name, or {@code '_'} for long-only
options
+ * @param details the option attributes in Commons CLI form
+ * @param description the option description
+ * @return the constructed option specification
*/
CommandLine.Model.OptionSpec option(shortname, Map details, description) {
CommandLine.Model.OptionSpec.Builder builder
diff --git a/src/main/groovy/groovy/concurrent/Dataflows.groovy
b/src/main/groovy/groovy/concurrent/Dataflows.groovy
index 34416e4f37..80ba77d86c 100644
--- a/src/main/groovy/groovy/concurrent/Dataflows.groovy
+++ b/src/main/groovy/groovy/concurrent/Dataflows.groovy
@@ -53,6 +53,9 @@ class Dataflows {
/**
* Reading a property awaits the corresponding DataflowVariable's value.
* Creates the variable on demand if it doesn't exist yet.
+ *
+ * @param name the variable name
+ * @return the bound value of the variable
*/
def propertyMissing(String name) {
AsyncSupport.await(getOrCreate(name))
@@ -61,6 +64,9 @@ class Dataflows {
/**
* Writing a property binds the corresponding DataflowVariable.
* Creates the variable on demand if it doesn't exist yet.
+ *
+ * @param name the variable name
+ * @param value the value to bind
*/
void propertyMissing(String name, value) {
getOrCreate(name).bind(value)
@@ -80,6 +86,9 @@ class Dataflows {
/**
* Returns {@code true} if the named variable has been bound.
+ *
+ * @param name the variable name
+ * @return {@code true} if the variable exists and has been bound
*/
boolean isBound(String name) {
def v = variables.get(name)
diff --git a/src/main/groovy/groovy/grape/GrapeUtil.groovy
b/src/main/groovy/groovy/grape/GrapeUtil.groovy
index 900403efab..3ad24eb3db 100644
--- a/src/main/groovy/groovy/grape/GrapeUtil.groovy
+++ b/src/main/groovy/groovy/grape/GrapeUtil.groovy
@@ -48,6 +48,9 @@ class GrapeUtil {
/**
* Adds a URI to a classloader's classpath via reflection.
+ *
+ * @param loader the class loader to update
+ * @param uri the URI to add to the class path
*/
static void addURL(ClassLoader loader, URI uri) {
// Dynamic invocation needed as addURL is not part of ClassLoader
interface
diff --git a/src/main/groovy/groovy/transform/ConditionalInterrupt.groovy
b/src/main/groovy/groovy/transform/ConditionalInterrupt.groovy
index 409b1c3238..d0159db24b 100644
--- a/src/main/groovy/groovy/transform/ConditionalInterrupt.groovy
+++ b/src/main/groovy/groovy/transform/ConditionalInterrupt.groovy
@@ -118,6 +118,7 @@ import java.lang.annotation.Target
*
* For even finer-grained control see {@code applyToAllMembers}.
*
+ * @return {@code true} if interrupt checks apply to all classes in the
compilation unit
* @see #applyToAllMembers()
*/
boolean applyToAllClasses() default true
@@ -130,23 +131,31 @@ import java.lang.annotation.Target
* Set to true (the default) for blanket coverage of conditional checks on
all methods, loops
* and closures within the class/script.
*
- * @since 2.2.0* @see #applyToAllClasses()
+ * @return {@code true} if interrupt checks apply to all members of the
annotated class or script
+ * @since 2.2.0
+ * @see #applyToAllClasses()
*/
boolean applyToAllMembers() default true
/**
* By default a conditional check is added to the start of all
user-defined methods. To turn this off simply
* set this parameter to false.
+ *
+ * @return {@code true} if the condition is evaluated at method entry
*/
boolean checkOnMethodStart() default true
/**
* Sets the type of exception which is thrown.
+ *
+ * @return the exception type thrown when the condition evaluates to
{@code true}
*/
Class thrown() default InterruptedException
/**
* Conditional check - set as a closure expression.
+ *
+ * @return the closure expression used to decide whether execution should
be interrupted
*/
Class value()
}
diff --git a/src/main/groovy/groovy/transform/Immutable.groovy
b/src/main/groovy/groovy/transform/Immutable.groovy
index 1a53efcfc6..7bbc68f760 100644
--- a/src/main/groovy/groovy/transform/Immutable.groovy
+++ b/src/main/groovy/groovy/transform/Immutable.groovy
@@ -201,12 +201,24 @@ import java.lang.annotation.Target
@Retention(RetentionPolicy.SOURCE)
@Target(ElementType.TYPE)
@interface Immutable {
- /** No longer used directly but instead collected from {@link
ImmutableOptions}. Remains for legacy handling only. */
+ /**
+ * No longer used directly but instead collected from {@link
ImmutableOptions}. Remains for legacy handling only.
+ *
+ * @return additional classes treated as immutable for legacy handling
+ */
Class[] knownImmutableClasses() default []
- /** No longer used directly but instead collected from {@link
ImmutableOptions}. Remains for legacy handling only. */
+ /**
+ * No longer used directly but instead collected from {@link
ImmutableOptions}. Remains for legacy handling only.
+ *
+ * @return additional property names treated as immutable for legacy
handling
+ */
String[] knownImmutables() default []
- /** No longer used directly but instead collected from {@link
ImmutableBase}. Remains for legacy handling only. */
+ /**
+ * No longer used directly but instead collected from {@link
ImmutableBase}. Remains for legacy handling only.
+ *
+ * @return {@code true} if copy-with support should be enabled for legacy
handling
+ */
boolean copyWith() default false
}
diff --git a/src/main/groovy/groovy/transform/ThreadInterrupt.groovy
b/src/main/groovy/groovy/transform/ThreadInterrupt.groovy
index 4e0dcd0215..169403f4d2 100644
--- a/src/main/groovy/groovy/transform/ThreadInterrupt.groovy
+++ b/src/main/groovy/groovy/transform/ThreadInterrupt.groovy
@@ -115,6 +115,7 @@ import java.lang.annotation.Target
*
* For even finer-grained control see {@code applyToAllMembers}.
*
+ * @return {@code true} if interrupt checks apply to all classes in the
compilation unit
* @see #applyToAllMembers()
*/
boolean applyToAllClasses() default true
@@ -127,6 +128,7 @@ import java.lang.annotation.Target
* Set to true (the default) for blanket coverage of isInterrupted checks
on all methods, loops
* and closures within the class/script.
*
+ * @return {@code true} if interrupt checks apply to all members of the
annotated class or script
* @since 2.2.0
* @see #applyToAllClasses()
*/
@@ -135,11 +137,15 @@ import java.lang.annotation.Target
/**
* By default an isInterrupted check is added to the start of all
user-defined methods. To turn this off simply
* set this parameter to false.
+ *
+ * @return {@code true} if an interruption check is added at method entry
*/
boolean checkOnMethodStart() default true
/**
* Sets the type of exception which is thrown.
+ *
+ * @return the exception type thrown when the current thread is interrupted
*/
Class thrown() default InterruptedException
}
diff --git a/src/main/groovy/groovy/transform/TimedInterrupt.groovy
b/src/main/groovy/groovy/transform/TimedInterrupt.groovy
index 9dd559f6c8..1b10be3d52 100644
--- a/src/main/groovy/groovy/transform/TimedInterrupt.groovy
+++ b/src/main/groovy/groovy/transform/TimedInterrupt.groovy
@@ -97,6 +97,7 @@ import java.util.concurrent.TimeoutException
*
* For even finer-grained control see {@code applyToAllMembers}.
*
+ * @return {@code true} if timeout checks apply to all classes in the
compilation unit
* @see #applyToAllMembers()
*/
boolean applyToAllClasses() default true
@@ -110,28 +111,38 @@ import java.util.concurrent.TimeoutException
* Set to true (the default) for blanket coverage of timeout checks on all
methods, loops
* and closures within the class/script.
*
- * @since 2.2.0* @see #applyToAllClasses()
+ * @return {@code true} if timeout checks apply to all members of the
annotated class or script
+ * @since 2.2.0
+ * @see #applyToAllClasses()
*/
boolean applyToAllMembers() default true
/**
* By default a time check is added to the start of all user-defined
methods. To turn this off
* simply set this parameter to false.
+ *
+ * @return {@code true} if a timeout check is added at method entry
*/
boolean checkOnMethodStart() default true
/**
- * The maximum elapsed time the script will be allowed to run for. By
default it is measure in seconds
+ * The maximum elapsed time the script will be allowed to run for. By
default it is measured in seconds.
+ *
+ * @return the timeout threshold
*/
long value()
/**
* The TimeUnit of the value parameter. By default it is TimeUnit.SECONDS.
+ *
+ * @return the time unit for {@link #value()}
*/
TimeUnit unit() default TimeUnit.SECONDS
/**
* The type of exception thrown when timeout is reached.
+ *
+ * @return the exception type thrown when the timeout expires
*/
Class thrown() default TimeoutException
}
diff --git a/src/main/groovy/groovy/util/ConfigSlurper.groovy
b/src/main/groovy/groovy/util/ConfigSlurper.groovy
index d4530dd3bf..76394d905a 100644
--- a/src/main/groovy/groovy/util/ConfigSlurper.groovy
+++ b/src/main/groovy/groovy/util/ConfigSlurper.groovy
@@ -111,6 +111,8 @@ class ConfigSlurper {
/**
* Sets any additional variables that should be placed into the binding
when evaluating Config scripts
+ *
+ * @param vars the variables to expose to configuration scripts
*/
void setBinding(Map vars) {
this.bindingVars = vars
@@ -119,7 +121,8 @@ class ConfigSlurper {
/**
* Parses a ConfigObject instances from an instance of java.util.Properties
*
- * @param The java.util.Properties instance
+ * @param properties the properties to convert
+ * @return the parsed configuration object
*/
ConfigObject parse(Properties properties) {
ConfigObject config = new ConfigObject()
@@ -166,6 +169,8 @@ class ConfigSlurper {
/**
* Parse the given script as a string and return the configuration object
*
+ * @param script the script text to parse
+ * @return the parsed configuration object
* @see ConfigSlurper#parse(groovy.lang.Script)
*/
ConfigObject parse(String script) {
@@ -175,6 +180,8 @@ class ConfigSlurper {
/**
* Create a new instance of the given script class and parse a
configuration object from it
*
+ * @param scriptClass the script class to instantiate
+ * @return the parsed configuration object
* @see ConfigSlurper#parse(groovy.lang.Script)
*/
ConfigObject parse(Class scriptClass) {
diff --git a/src/main/groovy/groovy/util/FileTreeBuilder.groovy
b/src/main/groovy/groovy/util/FileTreeBuilder.groovy
index 92b7875f2b..6ed0d97ffd 100644
--- a/src/main/groovy/groovy/util/FileTreeBuilder.groovy
+++ b/src/main/groovy/groovy/util/FileTreeBuilder.groovy
@@ -114,7 +114,7 @@ class FileTreeBuilder {
/**
* Creates a file with the specified name and the contents from the source
file (copy).
* @param name name of the file to be created
- * @param contents the contents of the file
+ * @param source the source file to copy
* @return the file being created
*/
File file(String name, File source) {
