| package org.checkerframework.common.returnsreceiver.qual; |
| |
| import java.lang.annotation.ElementType; |
| import java.lang.annotation.Retention; |
| import java.lang.annotation.RetentionPolicy; |
| import java.lang.annotation.Target; |
| import org.checkerframework.framework.qual.PolymorphicQualifier; |
| import org.checkerframework.framework.qual.TargetLocations; |
| import org.checkerframework.framework.qual.TypeUseLocation; |
| |
| /** |
| * Write {@code @This} on the return type of a method that always returns its receiver ({@code |
| * this}). For example: |
| * |
| * <pre><code> |
| * class MyBuilder { |
| * @This MyBuilder setName(String name) { |
| * this.name = name; |
| * return this; |
| * } |
| * } |
| * </code></pre> |
| * |
| * <p>Strictly speaking, this is a polymorphic annotation, but when you write it on a return type, |
| * the Returns Receiver Checker automatically adds it to the receiver, so the above method is |
| * equivalent to: |
| * |
| * <pre><code> |
| * @This MyBuilder setName(@This MyBuilder this, String name) { |
| * this.name = name; |
| * return this; |
| * } |
| * </code></pre> |
| * |
| * <p>While it would be natural to make {@code @This} the default annotation for receivers, it leads |
| * to false positives warnings due to <a |
| * href="https://github.com/typetools/checker-framework/issues/2931">https://github.com/typetools/checker-framework/issues/2931</a>, |
| * so this defaulting is currently elided. |
| * |
| * @checker_framework.manual #returns-receiver-checker Returns Receiver Checker |
| * @checker_framework.manual #qualifier-polymorphism Qualifier polymorphism |
| */ |
| @Retention(RetentionPolicy.RUNTIME) |
| @Target({ElementType.TYPE_USE, ElementType.TYPE_PARAMETER}) |
| @PolymorphicQualifier |
| @TargetLocations({TypeUseLocation.RECEIVER, TypeUseLocation.RETURN}) |
| public @interface This {} |