Until we can provide the same guarantees for core plugins, we need to be more conservative for existing classes and not follow best practices. This means conventions need to be set in both a plugin and the constructor. This keeps existing builds working, but it may complicate the implementation.

This is preferred for entirely new things:

```groovy
public interface NewThing {

 *
 * <p>A few notes about IPv6 "IPv4 mapped" addresses and their observed use in Java.
 *
 * <p>"IPv4 mapped" addresses were originally a representation of IPv4 addresses for use on an IPv6
 * socket that could receive both IPv4 and IPv6 connections (by disabling the {@code IPV6_V6ONLY}
 * socket option on an IPv6 socket). Yes, it's confusing. Nevertheless, these "mapped" addresses

   *
   * <ul>
   *   <li>normalNormal: two params, neither is Nullable
   *   <li>nullableNormal: only first param is Nullable
   *   <li>normalNullable: only second param is Nullable
   *   <li>nullableNullable: both params are Nullable
   * </ul>
   */
  public static class TwoArg {
    /** Action to take on a null param. */
    public enum Action {
      THROW_A_NPE {
        @Override
        public void act() {

    }
  }

  /**
   * Asserts that {@code transformation} is diagonal (i.e. neither horizontal nor vertical) and
   * passes through both {@code (x1, y1)} and {@code (x1 + xDelta, y1 + yDelta)}. Includes
   * assertions about all the public instance methods of {@link LinearTransformation} (on both
   * {@code transformation} and its inverse). Since the transformation is expected to be diagonal,

      case HALF_UP:
      case HALF_EVEN:
        BigInteger halfSquare = sqrtFloor.pow(2).add(sqrtFloor);
        /*
         * We wish to test whether or not x <= (sqrtFloor + 0.5)^2 = halfSquare + 0.25. Since both x
         * and halfSquare are integers, this is equivalent to testing whether or not x <=
         * halfSquare.
         */
        return (halfSquare.compareTo(x) >= 0) ? sqrtFloor : sqrtFloor.add(BigInteger.ONE);

	// ErrObjectLockInvalidHeaders indicates that object lock headers are missing
	ErrObjectLockInvalidHeaders = errors.New("x-amz-object-lock-retain-until-date and x-amz-object-lock-mode must both be supplied")
	// ErrMalformedXML - generic error indicating malformed XML
	ErrMalformedXML = errors.New("the XML you provided was not well-formed or did not validate against our published schema")
)

const (

     * directed; if it is undirected, the added edge will be undirected.
     *
     * <p>If this graph is directed, {@code endpoints} must be ordered.
     *
     * <p>If either or both endpoints are not already present in this graph, this method will
     * silently {@link #addNode(Object) add} each missing endpoint to the graph.
     *
     * @return this {@code Builder} object

Interceptors can be chained. Suppose you have both a compressing interceptor and a checksumming interceptor: you'll need to decide whether data is compressed and then checksummed, or checksummed and then compressed. OkHttp uses lists to track interceptors, and interceptors are called in order.

            UpgradeContext context = createMockContext();
            Map<Path, Document> pomMap = Map.of(Paths.get("pom.xml"), mock(Document.class));

            // Mock strategies that both modify the same POM
            when(mockStrategies.get(0).isApplicable(context)).thenReturn(true);
            when(mockStrategies.get(0).apply(Mockito.eq(context), Mockito.any()))
                    .thenReturn(

You can probably skip this part.

///

There's an alternative way to define this logic to be executed during *startup* and during *shutdown*.