diff options
Diffstat (limited to 'platform/annotations')
3 files changed, 23 insertions, 16 deletions
diff --git a/platform/annotations/src/org/intellij/lang/annotations/Flow.java b/platform/annotations/src/org/intellij/lang/annotations/Flow.java index c73fa57bf9f4..212103e904c9 100644 --- a/platform/annotations/src/org/intellij/lang/annotations/Flow.java +++ b/platform/annotations/src/org/intellij/lang/annotations/Flow.java @@ -19,14 +19,14 @@ import org.jetbrains.annotations.NonNls; import java.lang.annotation.*; -@Retention(RetentionPolicy.CLASS) -@Target({ElementType.PARAMETER, ElementType.METHOD}) /** * This annotation assists the 'Data flow to this' feature by describing data flow * from the method parameter to the corresponding container (e.g. <code>ArrayList.add(item)</code>) * or from the container to the method return value (e.g. <code>Set.toArray()</code>) * or between method parameters (e.g. <code>System.arraycopy(array1, 0, array2, length)</code>) */ +@Retention(RetentionPolicy.CLASS) +@Target({ElementType.PARAMETER, ElementType.METHOD}) public @interface Flow { /** * Denotes the source of the data flow.<br> @@ -66,7 +66,7 @@ public @interface Flow { /** * true if the data source is container and we should track not the expression but its contents.<br> * E.g. the java.util.ArrayList constructor takes the collection and stores its contents:<br> - * {@code ArrayList(@Flow(sourceIsContainer=true, targetIsContainer=true) Collection<? extends E> collection)}<br> + * ArrayList(<tt><pre>{@code @Flow(sourceIsContainer=true, targetIsContainer=true) Collection<? extends E> collection }</pre></tt>) <br> * By default it's false. */ boolean sourceIsContainer() default false; diff --git a/platform/annotations/src/org/intellij/lang/annotations/MagicConstant.java b/platform/annotations/src/org/intellij/lang/annotations/MagicConstant.java index 93f11fb116e5..c13cd9db3362 100644 --- a/platform/annotations/src/org/intellij/lang/annotations/MagicConstant.java +++ b/platform/annotations/src/org/intellij/lang/annotations/MagicConstant.java @@ -1,5 +1,5 @@ /* - * Copyright 2000-2012 JetBrains s.r.o. + * Copyright 2000-2014 JetBrains s.r.o. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -84,10 +84,11 @@ public @interface MagicConstant { /** * @return int values (typically named constants) which are allowed here. * E.g. - * <tt> + * <tt><pre> + * {@code * void setConfirmOpenNewProject(@MagicConstant(intValues = {OPEN_PROJECT_ASK, OPEN_PROJECT_NEW_WINDOW, OPEN_PROJECT_SAME_WINDOW}) * int confirmOpenNewProject); - * </tt> + * }</pre></tt> */ long[] intValues() default {}; @@ -100,13 +101,13 @@ public @interface MagicConstant { * @return allowed int flags (i.e. values (typically named constants) which can be combined with bitwise or operator (|). * Also 0 and -1 are considered allowed. * E.g. - * <tt> - * @MagicConstant(flags = {HierarchyEvent.PARENT_CHANGED,HierarchyEvent.DISPLAYABILITY_CHANGED,HierarchyEvent.SHOWING_CHANGED}) + * <tt><pre> + * {@code @MagicConstant(flags = {HierarchyEvent.PARENT_CHANGED,HierarchyEvent.DISPLAYABILITY_CHANGED,HierarchyEvent.SHOWING_CHANGED}) * int hFlags; * * hFlags = 3; // not allowed * if (hFlags & (HierarchyEvent.PARENT_CHANGED | HierarchyEvent.SHOWING_CHANGED) != 0); // OK - * </tt> + * }</pre></tt> */ long[] flags() default {}; @@ -114,27 +115,27 @@ public @interface MagicConstant { * @return allowed values which are defined in the specified class public static final constants. * * E.g. - * <tt> - * @MagicConstant(valuesFromClass = Cursor.class) + * <tt><pre> + * {@code @MagicConstant(valuesFromClass = Cursor.class) * int cursorType; * * cursorType = 11; // not allowed; * cursorType = Cursor.E_RESIZE_CURSOR; // OK - * </tt> + * }</pre></tt> */ Class valuesFromClass() default void.class; - /** * @return allowed int flags which are defined in the specified class public static final constants. * * E.g. - * <tt>@MagicConstant(flagsFromClass = java.awt.InputEvent.class) + * <tt><pre> + * {@code @MagicConstant(flagsFromClass = java.awt.InputEvent.class) * int eventMask; * * eventMask = 10; // not allowed; * eventMask = InputEvent.CTRL_MASK | InputEvent.ALT_MASK; // OK - * </tt> + * }</pre></tt> */ Class flagsFromClass() default void.class; } diff --git a/platform/annotations/src/org/jetbrains/annotations/Contract.java b/platform/annotations/src/org/jetbrains/annotations/Contract.java index 360bf5923d91..c1d08c483f74 100644 --- a/platform/annotations/src/org/jetbrains/annotations/Contract.java +++ b/platform/annotations/src/org/jetbrains/annotations/Contract.java @@ -54,7 +54,13 @@ public @interface Contract { String value() default ""; /** - * Specifies if this method is pure, i.e. has no visible side effects. This may be used for more precise data flow analysis, and + * Specifies that the annotated method has no visible side effects, in the following sense. + * If its return value is not used, removing its invocation won't + * affect program state and change the semantics. Such methods shouldn't throw exceptions by design, as exceptions affect semantics.<br><br> + * + * "Invisible" side effects (such as logging) that don't affect the "important" program semantics are allowed.<br><br> + * + * This annotation may be used for more precise data flow analysis, and * to check that the method's return value is actually used in the call place. */ boolean pure() default false; |