[JENKINS-43507] Should be first round complete for scm-api changes

src/main/java/jenkins/scm/api/trait/SCMNavigatorContext.java

@@ -259,7 +259,7 @@ public final C withDecorators(@NonNull Collection<? extends SCMSourceDecorator<?
      * Creates a new {@link SCMNavigatorRequest}.
      *
      * @param navigator the {@link SCMNavigator}.
-     * @param observer  the {@Link SCMSourceObserver}.
+     * @param observer  the {@link SCMSourceObserver}.
      * @return the {@link R}
      */
     @NonNull

src/main/java/jenkins/scm/api/trait/SCMSourceDecorator.java

@@ -30,23 +30,54 @@
 import jenkins.scm.api.SCMSource;
 import org.jvnet.tiger_types.Types;
 
+/**
+ * A contextual decorator of {@link SCMSourceBuilder} instances that can be used by a {@link SCMNavigatorTrait} for
+ * example to apply {@link SCMSourceTrait}s to a subset of projects.
+ *
+ * @param <B> the type of {@link SCMSourceBuilder}.
+ * @param <S> the type of {@link SCMSource}.
+ */
 public abstract class SCMSourceDecorator<B extends SCMSourceBuilder<B, S>, S extends SCMSource> {
 
+    /**
+     * A map of inferred {@link SCMSourceBuilder} classes to reduce the instantiation time cost of inferring the
+     * builder class from the type parameters of the implementation class.
+     */
     private static final WeakHashMap<Class<? extends SCMSourceDecorator>, Class<? extends SCMSourceBuilder>> builders
             = new WeakHashMap<Class<? extends SCMSourceDecorator>, Class<? extends SCMSourceBuilder>>();
 
+    /**
+     * The {@link B} class.
+     */
     private final Class<B> builderClass;
 
+    /**
+     * Infers the type of the corresponding {@link SCMSourceBuilder} from the type parameters of the implementation
+     * class. If the inference fails use {@link #SCMSourceDecorator(Class)}.
+     */
     protected SCMSourceDecorator() {
-        builderClass = SCMSourceDecorator.<B,S>lookupBuilderClass(getClass());
+        builderClass = SCMSourceDecorator.<B, S>inferBuilderClass(getClass());
     }
 
+    /**
+     * Bypasses {@link SCMSourceBuilder} type inference and specifies the type explicitly.
+     *
+     * @param builderClass the specialization of {@link SCMSourceBuilder} that this decorator applies to.
+     */
     protected SCMSourceDecorator(Class<B> builderClass) {
         this.builderClass = builderClass;
     }
 
+    /**
+     * Infers the type of builder class from the type of {@link SCMSourceDecorator}.
+     *
+     * @param clazz the type of {@link SCMSourceDecorator}
+     * @param <B>   coerces types by cheating (but this cheating is OK as we are deriving from type parameters)
+     * @param <S>   coerces types by cheating (but this cheating is OK as we are deriving from type parameters)
+     * @return the specialization of {@link SCMSourceBuilder} that the specified {@link SCMSourceDecorator} applies to.
+     */
     @SuppressWarnings("unchecked")
-    private static <B extends SCMSourceBuilder<B, S>, S extends SCMSource> Class<B> lookupBuilderClass(
+    private static <B extends SCMSourceBuilder<B, S>, S extends SCMSource> Class<B> inferBuilderClass(
             Class<? extends SCMSourceDecorator> clazz) {
         synchronized (builders) {
             Class result = builders.get(clazz);
@@ -71,11 +102,26 @@ protected SCMSourceDecorator(Class<B> builderClass) {
         }
     }
 
+    /**
+     * Applies this decorator to the specified {@link SCMSourceBuilder} for the supplied project name.
+     * If this {@link SCMSourceDecorator} is not specialized for the type of {@link SCMSourceBuilder} then this will
+     * be a no-op.
+     *
+     * @param builder     the {@link SCMSourceBuilder}.
+     * @param projectName the project name.
+     */
     public final void applyTo(SCMSourceBuilder<?, ?> builder, String projectName) {
         if (builderClass.isInstance(builder)) {
+            // we guard the SPI so that implementations can avoid casting while the API is generic so that
+            // consumers do not need to care about checking individual decorators for "fit"
             decorate(builderClass.cast(builder), projectName);
         }
     }
 
+    /**
+     * SPI: decorate the supplied builder for creation of the named project.
+     * @param builder the builder to decorate.
+     * @param projectName the project name.
+     */
     protected abstract void decorate(B builder, String projectName);
 }

src/main/java/jenkins/scm/api/trait/SCMSourceRequest.java

@@ -118,7 +118,7 @@
     /**
      * Constructor.
      *
-     * @param source  the source.
+     * @param source   the source.
      * @param context  the context.
      * @param listener the (optional) {@link TaskListener}.
      */
@@ -136,6 +136,22 @@ protected SCMSourceRequest(@NonNull SCMSource source, @NonNull SCMSourceContext<
         this.listener = defaultListener(listener);
     }
 
+    /**
+     * Records a processing result to the {@linkplain Witness}es.
+     *
+     * @param head      the {@link SCMHead}.
+     * @param revision  the {@link SCMRevision}.
+     * @param isMatch   {@code true} if the head:revision pair was sent to the {@link #observer}.
+     * @param witnesses the {@link Witness} instances to notify.
+     */
+    @SuppressWarnings("unchecked")
+    private static void record(@NonNull SCMHead head, SCMRevision revision, boolean isMatch,
+                               @NonNull Witness... witnesses) {
+        for (Witness witness : witnesses) {
+            witness.record(head, revision, isMatch);
+        }
+    }
+
     /**
      * Turns a possibly {@code null} {@link TaskListener} reference into a guaranteed non-null reference.
      *
@@ -156,22 +172,6 @@ private TaskListener defaultListener(@CheckForNull TaskListener listener) {
         return listener;
     }
 
-    /**
-     * Records a processing result to the {@linkplain Witness}es.
-     *
-     * @param head      the {@link SCMHead}.
-     * @param revision  the {@link SCMRevision}.
-     * @param isMatch   {@code true} if the head:revision pair was sent to the {@link #observer}.
-     * @param witnesses the {@link Witness} instances to notify.
-     */
-    @SuppressWarnings("unchecked")
-    private static void record(@NonNull SCMHead head, SCMRevision revision, boolean isMatch,
-                               @NonNull Witness... witnesses) {
-        for (Witness witness : witnesses) {
-            witness.record(head, revision, isMatch);
-        }
-    }
-
     /**
      * Tests if the {@link SCMHead} is excluded from the request.
      *
@@ -244,19 +244,22 @@ public final boolean isTrusted(@NonNull SCMHead head) throws IOException, Interr
      * @throws InterruptedException if the processing was interrupted.
      */
     public final <H extends SCMHead, R extends SCMRevision> boolean process(final @NonNull H head,
-                                                                            final R revision,
+                                                                            final @NonNull R revision,
                                                                             @NonNull ProbeLambda<H, R> probeFactory,
                                                                             @NonNull Witness... witnesses)
             throws IOException, InterruptedException {
         return process(head, new IntermediateLambda<R>() {
+            @Nullable
             @Override
             public R create() throws IOException, InterruptedException {
                 return revision;
             }
         }, probeFactory, new LazyRevisionLambda<H, SCMRevision, R>() {
+            @NonNull
             @Override
-            public SCMRevision create(H head, R intermediate) throws IOException, InterruptedException {
-                return intermediate;
+            public SCMRevision create(@NonNull H head, @Nullable R ignored)
+                    throws IOException, InterruptedException {
+                return revision;
             }
         }, witnesses);
     }
@@ -283,14 +286,18 @@ public SCMRevision create(H head, R intermediate) throws IOException, Interrupte
                                                                             @NonNull Witness... witnesses)
             throws IOException, InterruptedException {
         return process(head, new IntermediateLambda<R>() {
+            @NonNull
             @Override
             public R create() throws IOException, InterruptedException {
                 return revisionFactory.create(head);
             }
         }, probeFactory, new LazyRevisionLambda<H, SCMRevision, R>() {
+            @NonNull
             @Override
-            public SCMRevision create(H head, R intermediate) throws IOException, InterruptedException {
-                return intermediate;
+            public SCMRevision create(@NonNull H head, @Nullable R revision)
+                    throws IOException, InterruptedException {
+                assert revision != null;
+                return revision;
             }
         }, witnesses);
     }
@@ -335,7 +342,7 @@ public SCMRevision create(H head, R intermediate) throws IOException, Interrupte
             try {
                 for (SCMSourceCriteria c : criteria) {
                     if (!c.isHead(probe, listener)) {
-                        record((H) head, null, false, witnesses);
+                        record(head, null, false, witnesses);
                         // not a match against criteria
                         return !observer.isObserving();
                     }
@@ -423,6 +430,14 @@ public void close() throws IOException {
      * @param <R> the type of {@link SCMRevision}.
      */
     public interface RevisionLambda<H extends SCMHead, R extends SCMRevision> {
+        /**
+         * Creates a {@link SCMRevision} for the specified {@link SCMHead}.
+         *
+         * @param head the {@link SCMHead}.
+         * @return the {@link SCMRevision}.
+         * @throws IOException          if there is an I/O error.
+         * @throws InterruptedException if the operation was interrupted.
+         */
         @NonNull
         R create(@NonNull H head) throws IOException, InterruptedException;
     }
@@ -439,21 +454,23 @@ public void close() throws IOException {
      * @see IntermediateLambda
      */
     public interface ProbeLambda<H extends SCMHead, I> {
+        /**
+         * Creates a {@link SCMSourceCriteria.Probe} (ideally a {@link SCMProbe}) for the specified {@link SCMHead}
+         * and {@link SCMRevision} produced by {@link RevisionLambda} or intermediate produced by
+         * {@link IntermediateLambda}
+         *
+         * @param head         the {@link SCMHead}.
+         * @param revisionInfo depending on the type of {@link I} this is either a {@link SCMRevision} produced by a
+         *                     {@link RevisionLambda} or an intermediate produced by a {@link IntermediateLambda}.
+         *                     It could also be {@code null} if the implementation has captured sufficient information
+         *                     to create the {@link SCMSourceCriteria.Probe}.
+         * @return ideally a {@link SCMProbe}.
+         * @throws IOException          if there is an I/O error.
+         * @throws InterruptedException if the operation was interrupted.
+         */
         @NonNull
-        SCMSourceCriteria.Probe create(@NonNull H head, @Nullable I revision) throws IOException, InterruptedException;
-    }
-
-    /**
-     * A lambda that will create the {@link SCMRevision} instance for a specific {@link SCMHead} using the intermediate
-     * value produced by a {@link IntermediateLambda}.
-     * @param <H> the type of {@link SCMHead}
-     * @param <R> the type of {@link SCMRevision}.
-     * @param <I> the type of intermediate value produced by the {@link IntermediateLambda}.
-     *           @see IntermediateLambda
-     */
-    public interface LazyRevisionLambda<H extends SCMHead, R extends SCMRevision, I> {
-        @NonNull
-        R create(@NonNull H head, @Nullable I intermediate) throws IOException, InterruptedException;
+        SCMSourceCriteria.Probe create(@NonNull H head, @Nullable I revisionInfo)
+                throws IOException, InterruptedException;
     }
 
     /**
@@ -471,21 +488,66 @@ public void close() throws IOException {
      * the computation of the merge revision can be avoided completely.
      *
      * @param <I> the type of intermediate value or {@link Void} if no intermediate is required.
-     *           @see LazyRevisionLambda
-     *           @see ProbeLambda
+     * @see LazyRevisionLambda
+     * @see ProbeLambda
      */
     public interface IntermediateLambda<I> {
+
+        /**
+         * Creates an intermediate representation of the {@link SCMRevision} that can be used by {@link ProbeLambda}
+         * and {@link LazyRevisionLambda} to create the {@link SCMSourceCriteria.Probe} and {@link SCMRevision}
+         * respectively. This lambda is used where the creation of the {@link SCMRevision} may involve a
+         * <strong>more time costly</strong> operation that the creation of the {@link SCMSourceCriteria.Probe}.
+         *
+         * @return the intermediate (or {@code null} if the implementer of {@link ProbeLambda} and
+         * {@link LazyRevisionLambda} is expecting {@code null} under defined conditions).
+         * @throws IOException          if there is an I/O error.
+         * @throws InterruptedException if the operation was interrupted.
+         */
         @Nullable
         I create() throws IOException, InterruptedException;
     }
 
+    /**
+     * A lambda that will create the {@link SCMRevision} instance for a specific {@link SCMHead} using the intermediate
+     * value produced by a {@link IntermediateLambda}.
+     *
+     * @param <H> the type of {@link SCMHead}
+     * @param <R> the type of {@link SCMRevision}.
+     * @param <I> the type of intermediate value produced by the {@link IntermediateLambda}.
+     * @see IntermediateLambda
+     */
+    public interface LazyRevisionLambda<H extends SCMHead, R extends SCMRevision, I> {
+        /**
+         * Creates a {@link SCMRevision} for the specified {@link SCMHead} using the supplied intermediate previously
+         * generated by an {@link IntermediateLambda}.
+         *
+         * @param head         the {@link SCMHead}.
+         * @param intermediate the intermediate (may be {@code null} if no {@link IntermediateLambda} was provided
+         *                     or if the {@link IntermediateLambda} can return {@code null}.
+         * @return the {@link SCMRevision}.
+         * @throws IOException          if there is an I/O error.
+         * @throws InterruptedException if the operation was interrupted.
+         */
+        @NonNull
+        R create(@NonNull H head, @Nullable I intermediate) throws IOException, InterruptedException;
+    }
+
     /**
      * Callback lambda to track the results of
      * {@link #process(SCMHead, IntermediateLambda, ProbeLambda, LazyRevisionLambda, Witness[])}
+     *
      * @param <H> the type of {@link SCMHead}
      * @param <R> the type of {@link SCMRevision}
      */
     public interface Witness<H extends SCMHead, R extends SCMRevision> {
+        /**
+         * Records the result of a {@link SCMHead}.
+         *
+         * @param head     the {@link SCMHead}.
+         * @param revision (optional) the resolved {@link SCMRevision}.
+         * @param isMatch  {@code true} if the head matched.
+         */
         void record(@NonNull H head, @CheckForNull R revision, boolean isMatch);
     }
 }

src/main/java/jenkins/scm/api/trait/SCMSourceTrait.java

@@ -58,7 +58,8 @@ public final void applyToContext(SCMSourceContext<?, ?> context) {
      * SPI: Override this method to decorate a {@link SCMSourceContext}. You can assume that your
      * {@link SCMSourceTraitDescriptor#isApplicableToContext(Class)} is {@code true} within this method.
      *
-     * @param context the context (invariant: {@link SCMSourceTraitDescriptor#isApplicableToContext(Class)} is {@code true})
+     * @param context the context (invariant: {@link SCMSourceTraitDescriptor#isApplicableToContext(Class)} is {@code
+     *                true})
      * @param <B>     generic type parameter to ensure type information available.
      * @param <R>     generic type parameter to ensure type information available.
      */
@@ -131,21 +132,45 @@ protected boolean includeCategory(@NonNull SCMHeadCategory category) {
         return false;
     }
 
-    /** {@inheritDoc} */
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public SCMSourceTraitDescriptor getDescriptor() {
         return (SCMSourceTraitDescriptor) super.getDescriptor();
     }
 
+    /**
+     * Returns all the {@link SCMSourceTraitDescriptor} instances.
+     *
+     * @return all the {@link SCMSourceTraitDescriptor} instances.
+     */
     public static DescriptorExtensionList<SCMSourceTrait, SCMSourceTraitDescriptor> all() {
         return SCMTrait.all(SCMSourceTrait.class);
     }
 
+    /**
+     * Returns the subset of {@link SCMSourceTraitDescriptor} instances that are applicable to the specified types
+     * of {@link SCMSourceContext} and {@link SCMSourceBuilder}.
+     *
+     * @param contextClass (optional) type of {@link SCMSourceContext}.
+     * @param builderClass (optional) type of {@link SCMBuilder}.
+     * @return the list of matching {@link SCMSourceTraitDescriptor} instances.
+     */
     public static List<SCMSourceTraitDescriptor> _for(Class<? extends SCMSourceContext> contextClass,
                                                       Class<? extends SCMBuilder> builderClass) {
         return _for(null, contextClass, builderClass);
     }
 
+    /**
+     * Returns the subset of {@link SCMSourceTraitDescriptor} instances that are applicable to the specified
+     * {@link SCMSourceDescriptor} and specified types of {@link SCMNavigatorContext} and {@link SCMSourceBuilder}.
+     *
+     * @param scmSource    (optional) {@link SCMSourceDescriptor}.
+     * @param contextClass (optional) type of {@link SCMSourceContext}.
+     * @param builderClass (optional) type of {@link SCMBuilder}.
+     * @return the list of matching {@link SCMSourceTraitDescriptor} instances.
+     */
     public static List<SCMSourceTraitDescriptor> _for(@CheckForNull SCMSourceDescriptor scmSource,
                                                       @CheckForNull Class<? extends SCMSourceContext> contextClass,
                                                       @CheckForNull Class<? extends SCMBuilder> builderClass) {