This is an automated email from the ASF dual-hosted git repository. gnodet pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/maven.git
commit c3361ab62296f35c5e8149a0633d450747a697c9 Author: Guillaume Nodet <[email protected]> AuthorDate: Thu Oct 13 17:35:27 2022 +0200 Fix javadoc issues --- .../maven/api/annotations/NotThreadSafe.java | 2 +- .../org/apache/maven/api/model/InputLocation.java | 15 +++++- .../org/apache/maven/api/model/InputSource.java | 4 ++ .../org/apache/maven/api/model/package-info.java | 4 +- api/maven-api-model/src/main/mdo/maven.mdo | 6 +-- api/maven-api-model/src/main/mdo/model.vm | 52 +++++++++++++++----- api/maven-api-settings/src/main/mdo/model.vm | 56 +++++++++++++++++----- api/maven-api-toolchain/src/main/mdo/model.vm | 56 +++++++++++++++++----- 8 files changed, 152 insertions(+), 43 deletions(-) diff --git a/api/maven-api-meta/src/main/java/org/apache/maven/api/annotations/NotThreadSafe.java b/api/maven-api-meta/src/main/java/org/apache/maven/api/annotations/NotThreadSafe.java index ae4a6286f..b33381dd7 100644 --- a/api/maven-api-meta/src/main/java/org/apache/maven/api/annotations/NotThreadSafe.java +++ b/api/maven-api-meta/src/main/java/org/apache/maven/api/annotations/NotThreadSafe.java @@ -26,7 +26,7 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** - * This annotation indicates that the annotated type is <bold>not</bold> threadsafe + * This annotation indicates that the annotated type is <strong>not</strong> threadsafe * and should only be used by a single thread. * * @see ThreadSafe diff --git a/api/maven-api-model/src/main/java/org/apache/maven/api/model/InputLocation.java b/api/maven-api-model/src/main/java/org/apache/maven/api/model/InputLocation.java index 5aff705b0..8be05dbaa 100644 --- a/api/maven-api-model/src/main/java/org/apache/maven/api/model/InputLocation.java +++ b/api/maven-api-model/src/main/java/org/apache/maven/api/model/InputLocation.java @@ -97,7 +97,12 @@ public class InputLocation } /** - * Method merge. + * Merges the {@code source} location into the {@code target} location. + * + * @param target the target location + * @param source the source location + * @param sourceDominant the boolean indicating of {@code source} is dominant compared to {@code target} + * @return the merged location */ public static InputLocation merge( InputLocation target, InputLocation source, boolean sourceDominant ) { @@ -132,7 +137,13 @@ public class InputLocation } //-- InputLocation merge( InputLocation, InputLocation, boolean ) /** - * Method merge. + * Merges the {@code source} location into the {@code target} location. + * This method is used when the locations refer to lists and also merges the indices. + * + * @param target the target location + * @param source the source location + * @param indices the list of integers for the indices + * @return the merged location */ public static InputLocation merge( InputLocation target, InputLocation source, Collection<Integer> indices ) { diff --git a/api/maven-api-model/src/main/java/org/apache/maven/api/model/InputSource.java b/api/maven-api-model/src/main/java/org/apache/maven/api/model/InputSource.java index 34c8bf642..37cb13c1f 100644 --- a/api/maven-api-model/src/main/java/org/apache/maven/api/model/InputSource.java +++ b/api/maven-api-model/src/main/java/org/apache/maven/api/model/InputSource.java @@ -39,6 +39,8 @@ public class InputSource /** * Get the path/URL of the POM or {@code null} if unknown. + * + * @return the location */ public String getLocation() { @@ -47,6 +49,8 @@ public class InputSource /** * Get the identifier of the POM in the format {@code <groupId>:<artifactId>:<version>}. + * + * @return the model id */ public String getModelId() { diff --git a/api/maven-api-model/src/main/java/org/apache/maven/api/model/package-info.java b/api/maven-api-model/src/main/java/org/apache/maven/api/model/package-info.java index bfcdbe273..0924cab90 100644 --- a/api/maven-api-model/src/main/java/org/apache/maven/api/model/package-info.java +++ b/api/maven-api-model/src/main/java/org/apache/maven/api/model/package-info.java @@ -1,7 +1,7 @@ // CHECKSTYLE_OFF: RegexpHeader /** * Maven POM (Project Object Model) classes, generated from <code>maven.mdo</code> model. - * The root class is {@link org.apache.maven.model.Model}. + * The root class is {@link org.apache.maven.api.model.Model}. */ package org.apache.maven.api.model; @@ -22,4 +22,4 @@ package org.apache.maven.api.model; * KIND, either express or implied. See the License for the * specific language governing permissions and limitations * under the License. - */ \ No newline at end of file + */ diff --git a/api/maven-api-model/src/main/mdo/maven.mdo b/api/maven-api-model/src/main/mdo/maven.mdo index 7bd835d09..8e6f14665 100644 --- a/api/maven-api-model/src/main/mdo/maven.mdo +++ b/api/maven-api-model/src/main/mdo/maven.mdo @@ -629,7 +629,7 @@ /** * @return a Map of plugins field with {@code Plugins#getKey()} as key - * @see org.apache.maven.model.Plugin#getKey() + * @see Plugin#getKey() */ public synchronized Map<String, Plugin> getPluginsAsMap() { @@ -2281,7 +2281,7 @@ } /** * @return a Map of executions field with {@code PluginExecution#getId()} as key - * @see org.apache.maven.model.PluginExecution#getId() + * @see PluginExecution#getId() */ public java.util.Map<String, PluginExecution> getExecutionsAsMap() { @@ -2884,7 +2884,7 @@ /** * @return a Map of reportSets field with {@code ReportSet#getId()} as key - * @see org.apache.maven.model.ReportSet#getId() + * @see ReportSet#getId() */ public java.util.Map<String, ReportSet> getReportSetsAsMap() { diff --git a/api/maven-api-model/src/main/mdo/model.vm b/api/maven-api-model/src/main/mdo/model.vm index 9240aeecd..60f013dc1 100644 --- a/api/maven-api-model/src/main/mdo/model.vm +++ b/api/maven-api-model/src/main/mdo/model.vm @@ -47,13 +47,13 @@ #set ( $dummy = $imports.add( "org.apache.maven.api.annotations.ThreadSafe" ) ) #foreach ( $field in $allFields ) #if ( $field.type == "java.util.List" ) - #set ( $dummy = $imports.add( "java.util.ArrayList" ) ) - #set ( $dummy = $imports.add( "java.util.Collection" ) ) - #set ( $dummy = $imports.add( "java.util.List" ) ) - #set ( $dummy = $types.put( $field, "List<" + $field.to + ">" ) ) + #set ( $dummy = $imports.add( "java.util.ArrayList" ) ) + #set ( $dummy = $imports.add( "java.util.Collection" ) ) + #set ( $dummy = $imports.add( "java.util.List" ) ) + #set ( $dummy = $types.put( $field, "List<" + $field.to + ">" ) ) #elseif ( $field.type == "java.util.Properties" ) - #set ( $dummy = $imports.add( "java.util.Map" ) ) - #set ( $dummy = $types.put( $field, "Map<String, String>" ) ) + #set ( $dummy = $imports.add( "java.util.Map" ) ) + #set ( $dummy = $types.put( $field, "Map<String, String>" ) ) #elseif ( $field.type == "DOM" ) #set ( $dummy = $imports.add( "org.apache.maven.api.xml.Dom" ) ) #set ( $dummy = $types.put( $field, "Dom" ) ) @@ -245,6 +245,8 @@ public class ${class.name} #foreach ( $line in ${desc.split("\n")} ) * ${line.trim()} #end + * + * @return a {@code ${type}} */ #if ( $field.type == "java.util.List" || $field.type == "java.util.Properties" ) @Nonnull @@ -285,6 +287,8 @@ public class ${class.name} #end /** * Creates a new builder with this object as the basis. + * + * @return a {@code Builder} */ @Nonnull public Builder with() @@ -297,7 +301,12 @@ public class ${class.name} #if ( $type.startsWith("List<") ) #set ( $type = ${type.replace('List<','Collection<')} ) #end - /** Creates a new ${class.name} instance using the specified ${field.name}. */ + /** + * Creates a new {@code ${class.name}} instance using the specified ${field.name}. + * + * @param ${field.name} the new {@code $type} to use + * @return a {@code ${class.name}} with the specified ${field.name} + */ @Nonnull public ${class.name} with${cap}( $type $field.name ) { @@ -306,9 +315,11 @@ public class ${class.name} #end /** - * Creates a new ${class.name} instance. + * Creates a new {@code ${class.name}} instance. * Equivalent to {@code newInstance( true )}. * @see #newInstance(boolean) + * + * @return a new {@code ${class.name}} */ @Nonnull public static ${class.name} newInstance() @@ -317,8 +328,11 @@ public class ${class.name} } /** - * Creates a new ${class.name} instance using default values or not. + * Creates a new {@code ${class.name}} instance using default values or not. * Equivalent to {@code newBuilder( withDefaults ).build()}. + * + * @param withDefaults the boolean indicating whether default values should be used + * @return a new {@code ${class.name}} */ @Nonnull public static ${class.name} newInstance( boolean withDefaults ) @@ -327,9 +341,11 @@ public class ${class.name} } /** - * Creates a new ${class.name} builder instance. + * Creates a new {@code ${class.name}} builder instance. * Equivalent to {@code newBuilder( true )}. * @see #newBuilder(boolean) + * + * @return a new {@code Builder} */ @Nonnull public static Builder newBuilder() @@ -338,7 +354,10 @@ public class ${class.name} } /** - * Creates a new ${class.name} builder instance using default values or not. + * Creates a new {@code ${class.name}} builder instance using default values or not. + * + * @param withDefaults the boolean indicating whether default values should be used + * @return a new {@code Builder} */ @Nonnull public static Builder newBuilder( boolean withDefaults ) @@ -347,8 +366,11 @@ public class ${class.name} } /** - * Creates a new ${class.name} builder instance using the specified object as a basis. + * Creates a new {@code ${class.name}} builder instance using the specified object as a basis. * Equivalent to {@code newBuilder( from, false )}. + * + * @param from the {@code ${class.name}} instance to use as a basis + * @return a new {@code Builder} */ @Nonnull public static Builder newBuilder( ${class.name} from ) @@ -357,7 +379,11 @@ public class ${class.name} } /** - * Creates a new ${class.name} builder instance using the specified object as a basis. + * Creates a new {@code ${class.name}} builder instance using the specified object as a basis. + * + * @param from the {@code ${class.name}} instance to use as a basis + * @param forceCopy the boolean indicating if a copy should be forced + * @return a new {@code Builder} */ @Nonnull public static Builder newBuilder( ${class.name} from, boolean forceCopy ) diff --git a/api/maven-api-settings/src/main/mdo/model.vm b/api/maven-api-settings/src/main/mdo/model.vm index a547db349..60f013dc1 100644 --- a/api/maven-api-settings/src/main/mdo/model.vm +++ b/api/maven-api-settings/src/main/mdo/model.vm @@ -245,6 +245,8 @@ public class ${class.name} #foreach ( $line in ${desc.split("\n")} ) * ${line.trim()} #end + * + * @return a {@code ${type}} */ #if ( $field.type == "java.util.List" || $field.type == "java.util.Properties" ) @Nonnull @@ -285,6 +287,8 @@ public class ${class.name} #end /** * Creates a new builder with this object as the basis. + * + * @return a {@code Builder} */ @Nonnull public Builder with() @@ -297,7 +301,12 @@ public class ${class.name} #if ( $type.startsWith("List<") ) #set ( $type = ${type.replace('List<','Collection<')} ) #end - /** Creates a new ${class.name} instance using the specified ${field.name}. */ + /** + * Creates a new {@code ${class.name}} instance using the specified ${field.name}. + * + * @param ${field.name} the new {@code $type} to use + * @return a {@code ${class.name}} with the specified ${field.name} + */ @Nonnull public ${class.name} with${cap}( $type $field.name ) { @@ -306,9 +315,11 @@ public class ${class.name} #end /** - * Creates a new ${class.name} instance. + * Creates a new {@code ${class.name}} instance. * Equivalent to {@code newInstance( true )}. * @see #newInstance(boolean) + * + * @return a new {@code ${class.name}} */ @Nonnull public static ${class.name} newInstance() @@ -317,8 +328,11 @@ public class ${class.name} } /** - * Creates a new ${class.name} instance using default values or not. + * Creates a new {@code ${class.name}} instance using default values or not. * Equivalent to {@code newBuilder( withDefaults ).build()}. + * + * @param withDefaults the boolean indicating whether default values should be used + * @return a new {@code ${class.name}} */ @Nonnull public static ${class.name} newInstance( boolean withDefaults ) @@ -327,9 +341,11 @@ public class ${class.name} } /** - * Creates a new ${class.name} builder instance. + * Creates a new {@code ${class.name}} builder instance. * Equivalent to {@code newBuilder( true )}. * @see #newBuilder(boolean) + * + * @return a new {@code Builder} */ @Nonnull public static Builder newBuilder() @@ -338,7 +354,10 @@ public class ${class.name} } /** - * Creates a new ${class.name} builder instance using default values or not. + * Creates a new {@code ${class.name}} builder instance using default values or not. + * + * @param withDefaults the boolean indicating whether default values should be used + * @return a new {@code Builder} */ @Nonnull public static Builder newBuilder( boolean withDefaults ) @@ -347,8 +366,11 @@ public class ${class.name} } /** - * Creates a new ${class.name} builder instance using the specified object as a basis. + * Creates a new {@code ${class.name}} builder instance using the specified object as a basis. * Equivalent to {@code newBuilder( from, false )}. + * + * @param from the {@code ${class.name}} instance to use as a basis + * @return a new {@code Builder} */ @Nonnull public static Builder newBuilder( ${class.name} from ) @@ -357,7 +379,11 @@ public class ${class.name} } /** - * Creates a new ${class.name} builder instance using the specified object as a basis. + * Creates a new {@code ${class.name}} builder instance using the specified object as a basis. + * + * @param from the {@code ${class.name}} instance to use as a basis + * @param forceCopy the boolean indicating if a copy should be forced + * @return a new {@code Builder} */ @Nonnull public static Builder newBuilder( ${class.name} from, boolean forceCopy ) @@ -485,11 +511,19 @@ public class ${class.name} return base; } #if ( $locationTracking ) - Map<Object, InputLocation> locations = new HashMap<>( this.locations != null ? this.locations : ( base != null ? base.locations : Collections.emptyMap() ) ); - InputLocation location = locations.remove( "" ); + Map<Object, InputLocation> locations = null; + InputLocation location = null; + #foreach ( $field in $allFields ) + InputLocation ${field.name}Location = null; + #end + if ( this.locations != null ) + { + locations = this.locations; + location = locations.remove( "" ); #foreach ( $field in $allFields ) - InputLocation ${field.name}Location = locations.remove( "${field.name}" ); + ${field.name}Location = locations.remove( "${field.name}" ); #end + } #end return new ${class.name}( #if ( $class == $root ) @@ -504,7 +538,7 @@ public class ${class.name} #end #end #if ( $locationTracking ) - locations, + locations != null ? locations : ( base != null ? base.locations : null ), #set ( $sep = "#if(${allFields.size()}>0),#end" ) location != null ? location : ( base != null ? base.location : null )${sep} #foreach ( $field in $allFields ) diff --git a/api/maven-api-toolchain/src/main/mdo/model.vm b/api/maven-api-toolchain/src/main/mdo/model.vm index a547db349..60f013dc1 100644 --- a/api/maven-api-toolchain/src/main/mdo/model.vm +++ b/api/maven-api-toolchain/src/main/mdo/model.vm @@ -245,6 +245,8 @@ public class ${class.name} #foreach ( $line in ${desc.split("\n")} ) * ${line.trim()} #end + * + * @return a {@code ${type}} */ #if ( $field.type == "java.util.List" || $field.type == "java.util.Properties" ) @Nonnull @@ -285,6 +287,8 @@ public class ${class.name} #end /** * Creates a new builder with this object as the basis. + * + * @return a {@code Builder} */ @Nonnull public Builder with() @@ -297,7 +301,12 @@ public class ${class.name} #if ( $type.startsWith("List<") ) #set ( $type = ${type.replace('List<','Collection<')} ) #end - /** Creates a new ${class.name} instance using the specified ${field.name}. */ + /** + * Creates a new {@code ${class.name}} instance using the specified ${field.name}. + * + * @param ${field.name} the new {@code $type} to use + * @return a {@code ${class.name}} with the specified ${field.name} + */ @Nonnull public ${class.name} with${cap}( $type $field.name ) { @@ -306,9 +315,11 @@ public class ${class.name} #end /** - * Creates a new ${class.name} instance. + * Creates a new {@code ${class.name}} instance. * Equivalent to {@code newInstance( true )}. * @see #newInstance(boolean) + * + * @return a new {@code ${class.name}} */ @Nonnull public static ${class.name} newInstance() @@ -317,8 +328,11 @@ public class ${class.name} } /** - * Creates a new ${class.name} instance using default values or not. + * Creates a new {@code ${class.name}} instance using default values or not. * Equivalent to {@code newBuilder( withDefaults ).build()}. + * + * @param withDefaults the boolean indicating whether default values should be used + * @return a new {@code ${class.name}} */ @Nonnull public static ${class.name} newInstance( boolean withDefaults ) @@ -327,9 +341,11 @@ public class ${class.name} } /** - * Creates a new ${class.name} builder instance. + * Creates a new {@code ${class.name}} builder instance. * Equivalent to {@code newBuilder( true )}. * @see #newBuilder(boolean) + * + * @return a new {@code Builder} */ @Nonnull public static Builder newBuilder() @@ -338,7 +354,10 @@ public class ${class.name} } /** - * Creates a new ${class.name} builder instance using default values or not. + * Creates a new {@code ${class.name}} builder instance using default values or not. + * + * @param withDefaults the boolean indicating whether default values should be used + * @return a new {@code Builder} */ @Nonnull public static Builder newBuilder( boolean withDefaults ) @@ -347,8 +366,11 @@ public class ${class.name} } /** - * Creates a new ${class.name} builder instance using the specified object as a basis. + * Creates a new {@code ${class.name}} builder instance using the specified object as a basis. * Equivalent to {@code newBuilder( from, false )}. + * + * @param from the {@code ${class.name}} instance to use as a basis + * @return a new {@code Builder} */ @Nonnull public static Builder newBuilder( ${class.name} from ) @@ -357,7 +379,11 @@ public class ${class.name} } /** - * Creates a new ${class.name} builder instance using the specified object as a basis. + * Creates a new {@code ${class.name}} builder instance using the specified object as a basis. + * + * @param from the {@code ${class.name}} instance to use as a basis + * @param forceCopy the boolean indicating if a copy should be forced + * @return a new {@code Builder} */ @Nonnull public static Builder newBuilder( ${class.name} from, boolean forceCopy ) @@ -485,11 +511,19 @@ public class ${class.name} return base; } #if ( $locationTracking ) - Map<Object, InputLocation> locations = new HashMap<>( this.locations != null ? this.locations : ( base != null ? base.locations : Collections.emptyMap() ) ); - InputLocation location = locations.remove( "" ); + Map<Object, InputLocation> locations = null; + InputLocation location = null; + #foreach ( $field in $allFields ) + InputLocation ${field.name}Location = null; + #end + if ( this.locations != null ) + { + locations = this.locations; + location = locations.remove( "" ); #foreach ( $field in $allFields ) - InputLocation ${field.name}Location = locations.remove( "${field.name}" ); + ${field.name}Location = locations.remove( "${field.name}" ); #end + } #end return new ${class.name}( #if ( $class == $root ) @@ -504,7 +538,7 @@ public class ${class.name} #end #end #if ( $locationTracking ) - locations, + locations != null ? locations : ( base != null ? base.locations : null ), #set ( $sep = "#if(${allFields.size()}>0),#end" ) location != null ? location : ( base != null ? base.location : null )${sep} #foreach ( $field in $allFields )
