jasder
/
antlr
1
0
Fork 1
Code Issues Pull Requests Releases 1 Wiki Activity

Updated documentation for NotNull and Nullable

This commit is contained in:
Sam Harwell 2014-01-21 15:24:57 -06:00
parent 07708d9223
commit 0454916a70
2 changed files with 76 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
runtime/JavaAnnotations/src/org/antlr/v4/runtime/misc/NotNull.java
View File

@ -30,8 +30,43 @@
package org.antlr.v4.runtime.misc;
@java.lang.annotation.Documented
@java.lang.annotation.Retention(java.lang.annotation.RetentionPolicy.CLASS)
@java.lang.annotation.Target({java.lang.annotation.ElementType.FIELD, java.lang.annotation.ElementType.METHOD, java.lang.annotation.ElementType.PARAMETER, java.lang.annotation.ElementType.LOCAL_VARIABLE})
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
* This annotation marks a field, parameter, local variable, or method (return
* value) as never being {@code null}. The specific semantics implied by this
* annotation depend on the kind of element the annotation is applied to.
*
* <ul>
* <li><strong>Field or Local Variable:</strong> Code reading the field or local
* variable may assume that the value is never {@code null}. Code writing to the
* field or local variable should ensure that a {@code null} reference is never
* written.</li>
* <li><strong>Parameter:</strong> Code calling the method should never pass
* {@code null} for this parameter. The implementation may assume that the value
* is never {@code null}, and the behavior of the method if the parameter is
* {@code null} is undefined. Overriding methods may optionally use the
* {@link Nullable} annotation instead of this annotation for the parameter,
* indicating that the overriding method provides additional code to handle a
* {@code null} reference passed for the parameter.</li>
* <li><strong>Method (Return Value):</strong> Code calling the method may
* assume that the result of the method is never {@code null}. The
* implementation of the method should ensure that a {@code null} reference is
* never returned.</li>
* </ul>
*
* <p>
* The {@link NullUsageProcessor} annotation processor validates certain usage
* scenarios for this annotation, with compile-time errors or warnings reported
* for misuse. For detailed information about the supported analysis, see the
* documentation for {@link NullUsageProcessor}.</p>
*/
@Documented
@Retention(RetentionPolicy.CLASS)
@Target({ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER, ElementType.LOCAL_VARIABLE})
public @interface NotNull {
}

41
runtime/JavaAnnotations/src/org/antlr/v4/runtime/misc/Nullable.java
View File

@ -30,8 +30,43 @@
package org.antlr.v4.runtime.misc;
@java.lang.annotation.Documented
@java.lang.annotation.Retention(java.lang.annotation.RetentionPolicy.CLASS)
@java.lang.annotation.Target({java.lang.annotation.ElementType.FIELD, java.lang.annotation.ElementType.METHOD, java.lang.annotation.ElementType.PARAMETER, java.lang.annotation.ElementType.LOCAL_VARIABLE})
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
* This annotation marks a field, parameter, local variable, or method (return
* value) as potentially having the value {@code null}. The specific semantics
* implied by this annotation depend on the kind of element the annotation is
* applied to.
*
* <ul>
* <li><strong>Field or Local Variable:</strong> Code reading the field or local
* variable may not assume that the value is never {@code null}.</li>
* <li><strong>Parameter:</strong> Code calling the method might pass
* {@code null} for this parameter. The documentation for the method should
* describe the behavior of the method in the event this parameter is
* {@code null}.
* </li>
* <li><strong>Method (Return Value):</strong> Code calling the method may not
* assume that the result of the method is never {@code null}. The documentation
* for the method should describe the meaning of a {@code null} reference being
* returned. Overriding methods may optionally use the {@link NotNull}
* annotation instead of this annotation for the method, indicating that the
* overriding method (and any method which overrides it) will never return a
* {@code null} reference.</li>
* </ul>
*
* <p>
* The {@link NullUsageProcessor} annotation processor validates certain usage
* scenarios for this annotation, with compile-time errors or warnings reported
* for misuse. For detailed information about the supported analysis, see the
* documentation for {@link NullUsageProcessor}.</p>
*/
@Documented
@Retention(RetentionPolicy.CLASS)
@Target({ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER, ElementType.LOCAL_VARIABLE})
public @interface Nullable {
}