/*
 * Copyright (C) 2020 The Dagger Authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package dagger.hilt.codegen;

/**
 * An annotation used to specify the originating element that triggered the code generation of a
 * type. This annotation should only be used on generated code and is meant to be used by code
 * generators that generate Hilt modules, entry points, etc. Failure to use this annotation may mean
 * improper test isolation for generated classes.
 *
 * <p>This annotation should be used on any generated top-level class that either contains generated
 * modules (or entry points) or contains annotations that will generate modules (or entry points).
 *
 * <p>Example: Suppose we have the following use of an annotation, {@code MyAnnotation}.
 *
 * <pre><code>
 *   class Outer {
 *     static class Inner {
 *       {@literal @}MyAnnotation Foo foo;
 *     }
 *   }
 * </code></pre>
 *
 * <p>If {@code MyAnnotation} generates an entry point, it should be annotated as follows:
 *
 * <pre><code>
 *   {@literal @}OriginatingElement(topLevelClass = Outer.class)
 *   {@literal @}EntryPoint
 *   {@literal @}InstallIn(SingletonComponent.class) {
 *       ...
 *   }
 * </code></pre>
 */
// TODO(bcorso): Consider just advising/enforcing that all top-level classes use this annotation.
public @interface OriginatingElement {
  /** Returns the top-level class enclosing the originating element. */
  Class<?> topLevelClass();
}