Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
[JENKINS-43507] Documenting SCMNavigatorTrait and SCMNavigatorTraitDe…
…scriptor
  • Loading branch information
stephenc committed May 4, 2017
1 parent f961638 commit 85c0577
Show file tree
Hide file tree
Showing 5 changed files with 120 additions and 23 deletions.
40 changes: 33 additions & 7 deletions src/main/java/jenkins/scm/api/trait/SCMNavigatorTrait.java
Expand Up @@ -24,11 +24,11 @@

package jenkins.scm.api.trait;

import edu.umd.cs.findbugs.annotations.CheckForNull;
import edu.umd.cs.findbugs.annotations.NonNull;
import hudson.DescriptorExtensionList;
import java.util.ArrayList;
import java.util.List;
import javax.annotation.CheckForNull;
import jenkins.scm.api.SCMHeadCategory;
import jenkins.scm.api.SCMNavigatorDescriptor;
import jenkins.scm.api.SCMSource;
Expand Down Expand Up @@ -130,24 +130,50 @@ protected boolean includeCategory(@NonNull SCMHeadCategory category) {
return false;
}

/** {@inheritDoc} */
/**
* {@inheritDoc}
*/
@Override
public SCMNavigatorTraitDescriptor getDescriptor() {
return (SCMNavigatorTraitDescriptor) super.getDescriptor();
}

/**
* Returns all the {@link SCMNavigatorTraitDescriptor} instances.
*
* @return all the {@link SCMNavigatorTraitDescriptor} instances.
*/
public static DescriptorExtensionList<SCMNavigatorTrait, SCMNavigatorTraitDescriptor> all() {
return SCMTrait.all(SCMNavigatorTrait.class);
}

public static List<SCMNavigatorTraitDescriptor> _for(Class<? extends SCMNavigatorContext> contextClass,
Class<? extends SCMSourceBuilder> builderClass) {
/**
* Returns the subset of {@link SCMNavigatorTraitDescriptor} instances that are applicable to the specified types
* of {@link SCMNavigatorContext} and {@link SCMSourceBuilder}.
*
* @param contextClass (optional) type of {@link SCMNavigatorContext}.
* @param builderClass (optional) type of {@link SCMSourceBuilder}.
* @return the list of matching {@link SCMNavigatorTraitDescriptor} instances.
*/
public static List<SCMNavigatorTraitDescriptor> _for(
@CheckForNull Class<? extends SCMNavigatorContext> contextClass,
@CheckForNull Class<? extends SCMSourceBuilder> builderClass) {
return _for(null, contextClass, builderClass);
}

public static List<SCMNavigatorTraitDescriptor> _for(@CheckForNull SCMNavigatorDescriptor scmNavigator,
@CheckForNull Class<? extends SCMNavigatorContext> contextClass,
@CheckForNull Class<? extends SCMSourceBuilder> builderClass) {
/**
* Returns the subset of {@link SCMNavigatorTraitDescriptor} instances that are applicable to the specified
* {@link SCMNavigatorDescriptor} and specified types of {@link SCMNavigatorContext} and {@link SCMSourceBuilder}.
*
* @param scmNavigator (optional) {@link SCMNavigatorDescriptor}.
* @param contextClass (optional) type of {@link SCMNavigatorContext}.
* @param builderClass (optional) type of {@link SCMSourceBuilder}.
* @return the list of matching {@link SCMNavigatorTraitDescriptor} instances.
*/
public static List<SCMNavigatorTraitDescriptor> _for(
@CheckForNull SCMNavigatorDescriptor scmNavigator,
@CheckForNull Class<? extends SCMNavigatorContext> contextClass,
@CheckForNull Class<? extends SCMSourceBuilder> builderClass) {
List<SCMNavigatorTraitDescriptor> result = new ArrayList<SCMNavigatorTraitDescriptor>();
if (scmNavigator != null) {
for (SCMNavigatorTraitDescriptor d : all()) {
Expand Down
Expand Up @@ -38,10 +38,20 @@
*/
public abstract class SCMNavigatorTraitDescriptor extends SCMTraitDescriptor<SCMNavigatorTrait> {

protected SCMNavigatorTraitDescriptor(Class<? extends SCMNavigatorTrait> clazz) {
/**
* Constructor to use when type inferrence using {@link #SCMNavigatorTraitDescriptor()} does not work.
*
* @param clazz Pass in the type of {@link SCMNavigatorTrait}
*/
protected SCMNavigatorTraitDescriptor(@NonNull Class<? extends SCMNavigatorTrait> clazz) {
super(clazz);
}

/**
* Infers the type of the corresponding {@link SCMNavigatorTrait} from the outer class.
* This version works when you follow the common convention, where a descriptor
* is written as the static nested class of the describable class.
*/
protected SCMNavigatorTraitDescriptor() {
super();
}
Expand All @@ -67,7 +77,7 @@ public boolean isApplicableToBuilder(@NonNull SCMSourceBuilder<?, ?> builder) {
}

/**
* Checks if the {@link SCMSourceTrait} is relevant to the specified type of {@link SCMNavigatorContext}.
* Checks if the {@link SCMNavigatorTrait} is relevant to the specified type of {@link SCMNavigatorContext}.
*
* @param contextClass the type of {@link SCMSourceContext}.
* @return {@code true} if applicable to the specified type of {@link SCMSourceContext}.
Expand All @@ -77,7 +87,7 @@ public boolean isApplicableToContext(@NonNull Class<? extends SCMNavigatorContex
}

/**
* Checks if the {@link SCMSourceTrait} is relevant to the specified {@link SCMNavigatorContext}.
* Checks if the {@link SCMNavigatorTrait} is relevant to the specified {@link SCMNavigatorContext}.
*
* @param context the {@link SCMNavigatorContext}.
* @return {@code true} if applicable to the specified type of {@link SCMNavigatorContext}.
Expand All @@ -86,23 +96,63 @@ public boolean isApplicableToContext(@NonNull SCMNavigatorContext context) {
return isApplicableToContext(context.getClass());
}

public boolean isApplicableToSource(SCMSource source) {
/**
* Checks if the {@link SCMNavigatorTrait} is relevant to the specified {@link SCMSource}.
*
* @param source the {@link SCMSource}.
* @return {@code true} if applicable to the specified {@link SCMSource}.
*/
public boolean isApplicableToSource(@NonNull SCMSource source) {
return isApplicableToSource(source.getDescriptor());
}

public boolean isApplicableToSource(SCMSourceDescriptor descriptor) {
/**
* Checks if the {@link SCMNavigatorTrait} is relevant to the specified {@link SCMSourceDescriptor}.
*
* @param descriptor the {@link SCMSourceDescriptor}.
* @return {@code true} if applicable to the specified {@link SCMSourceDescriptor}.
*/
public boolean isApplicableToSource(@NonNull SCMSourceDescriptor descriptor) {
return isApplicableToSource(descriptor.getT());
}

public boolean isApplicableToSource(Class<? extends SCMSource> sourceClass) {
/**
* Checks if the {@link SCMNavigatorTrait} is relevant to the specified type of {@link SCMSource}.
*
* @param sourceClass the type of {@link SCMSource}.
* @return {@code true} if applicable to the specified type of {@link SCMSource}.
*/
public boolean isApplicableToSource(@NonNull Class<? extends SCMSource> sourceClass) {
return true;
}

public boolean isApplicableTo(SCMNavigator navigator) {
/**
* Checks if the {@link SCMNavigatorTrait} is relevant to the specified {@link SCMNavigator}.
*
* @param navigator the {@link SCMNavigator}.
* @return {@code true} if applicable to the specified {@link SCMNavigator}.
*/
public boolean isApplicableTo(@NonNull SCMNavigator navigator) {
return isApplicableTo(navigator.getDescriptor());
}

public boolean isApplicableTo(SCMNavigatorDescriptor descriptor) {
/**
* Checks if the {@link SCMNavigatorTrait} is relevant to the specified {@link SCMNavigatorDescriptor}.
*
* @param descriptor the {@link SCMNavigatorDescriptor}.
* @return {@code true} if applicable to the specified {@link SCMNavigatorDescriptor}.
*/
public boolean isApplicableTo(@NonNull SCMNavigatorDescriptor descriptor) {
return isApplicableTo(descriptor.getT());
}

/**
* Checks if the {@link SCMNavigatorTrait} is relevant to the specified type of {@link SCMNavigator}.
*
* @param navigatorClass the type of {@link SCMNavigator}.
* @return {@code true} if applicable to the specified type of {@link SCMNavigator}.
*/
public boolean isApplicableTo(@NonNull Class<? extends SCMNavigator> navigatorClass) {
return true;
}

Expand Down
5 changes: 2 additions & 3 deletions src/main/java/jenkins/scm/api/trait/SCMSourceBuilder.java
Expand Up @@ -25,7 +25,6 @@
package jenkins.scm.api.trait;

import edu.umd.cs.findbugs.annotations.NonNull;
import hudson.scm.SCM;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collection;
Expand Down Expand Up @@ -82,7 +81,7 @@ public abstract class SCMSourceBuilder<B extends SCMSourceBuilder<B, S>, S exten
* @param clazz the base class of {@link SCMSource} that will be produced by the {@link SCMSourceBuilder}.
* @param projectName the project name.
*/
public SCMSourceBuilder(Class<S> clazz, String projectName) {
public SCMSourceBuilder(@NonNull Class<S> clazz, @NonNull String projectName) {
this.clazz = clazz;
this.projectName = projectName;
}
Expand Down Expand Up @@ -183,7 +182,7 @@ public B withTraits(@NonNull Collection<? extends SCMTrait<?>> traits) {
* @return {@code this} for method chaining.
*/
@SuppressWarnings("unchecked")
public B withRequest(SCMNavigatorRequest request) {
public B withRequest(@NonNull SCMNavigatorRequest request) {
withTraits(request.traits());
for (SCMSourceDecorator<?,?> decorator: request.decorators()) {
decorator.applyTo(this, projectName());
Expand Down
28 changes: 25 additions & 3 deletions src/main/java/jenkins/scm/api/trait/SCMSourceTraitDescriptor.java
Expand Up @@ -41,7 +41,7 @@ public abstract class SCMSourceTraitDescriptor extends SCMTraitDescriptor<SCMSou
*
* @param clazz Pass in the type of {@link SCMTrait}
*/
protected SCMSourceTraitDescriptor(Class<? extends SCMSourceTrait> clazz) {
protected SCMSourceTraitDescriptor(@NonNull Class<? extends SCMSourceTrait> clazz) {
super(clazz);
}

Expand Down Expand Up @@ -94,11 +94,33 @@ public boolean isApplicableToContext(@NonNull SCMSourceContext context) {
return isApplicableToContext(context.getClass());
}

public boolean isApplicableTo(SCMSource source) {
/**
* Checks if the {@link SCMSourceTrait} is relevant to the specified {@link SCMSource}.
*
* @param source the {@link SCMSource}.
* @return {@code true} if applicable to the specified {@link SCMSource}.
*/
public boolean isApplicableTo(@NonNull SCMSource source) {
return isApplicableTo(source.getDescriptor());
}

public boolean isApplicableTo(SCMSourceDescriptor descriptor) {
/**
* Checks if the {@link SCMSourceTrait} is relevant to the specified {@link SCMSourceDescriptor}.
*
* @param descriptor the {@link SCMSourceDescriptor}.
* @return {@code true} if applicable to the specified {@link SCMSourceDescriptor}.
*/
public boolean isApplicableTo(@NonNull SCMSourceDescriptor descriptor) {
return isApplicableTo(descriptor.getT());
}

/**
* Checks if the {@link SCMSourceTrait} is relevant to the specified type of {@link SCMSource}.
*
* @param sourceClass the type of {@link SCMSource}.
* @return {@code true} if applicable to the specified type of {@link SCMSource}.
*/
public boolean isApplicableTo(@NonNull Class<? extends SCMSource> sourceClass) {
return true;
}

Expand Down
4 changes: 2 additions & 2 deletions src/main/java/jenkins/scm/api/trait/SCMTraitDescriptor.java
Expand Up @@ -41,7 +41,7 @@ public abstract class SCMTraitDescriptor<T extends SCMTrait<T>> extends Descript
*
* @param clazz Pass in the type of {@link SCMTrait}
*/
protected SCMTraitDescriptor(Class<? extends T> clazz) {
protected SCMTraitDescriptor(@NonNull Class<? extends T> clazz) {
super(clazz);
}

Expand All @@ -60,7 +60,7 @@ protected SCMTraitDescriptor() {
* @param scm the {@link SCMDescriptor} for the type of {@link SCM}.
* @return {@code true} if applicable to the specified type of {@link SCM}.
*/
public boolean isApplicableToSCM(SCMDescriptor<?> scm) {
public boolean isApplicableToSCM(@NonNull SCMDescriptor<?> scm) {
return isApplicableToSCM(scm.getT());
}

Expand Down

0 comments on commit 85c0577

Please sign in to comment.