Skip to content
Commits on Source (9)
Show whitespace changes
Inline Side-by-side
CONTRIBUTING.md 0 → 100644
View file @ 8d517251
### How to contribute
If you are not a JetBrains' employee you must sign [Contributor License Agreement](https://www.jetbrains.org/display/IJOS/Contributor+Agreement) first.
You may do it [electronically](https://www.jetbrains.com/agreements/cla/). After that send your changes as a pull request or commit them directly to a branch.
### Versioning
Update `projectVersion` property in gradle.properties file before doing the change:
* increase the patch component of the version if you're changing a javadoc
* increase the minor component of the version if you're adding a new element into an existing annotation or add
a new annotation highly related to an existing one
* increase the major component of the version if you're adding a completely new annotation.
Also update version number in the examples in README.md file.
### Backward compatibility
All the changes should be backward compatible i.e. you can add new annotations and new elements into existing annotation.
If it's absolutely necessary to remove an annotation or its element we must firstly release a new major version where
the corresponding element is marked as deprecated and then remove it in one of the next major versions.
\ No newline at end of file
LICENSE.txt 0 → 100644
View file @ 8d517251
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright 2000-2016 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.
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.
README.md 0 → 100644
View file @ 8d517251
# Annotations for JVM-based languages
[![official JetBrains project](http://jb.gg/badges/official.svg)](https://confluence.jetbrains.com/display/ALL/JetBrains+on+GitHub) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![Maven Central](https://maven-badges.herokuapp.com/maven-central/org.jetbrains/annotations/badge.svg)](https://maven-badges.herokuapp.com/maven-central/org.jetbrains/annotations)
A set of Java annotations which can be used in JVM-based languages. They serve as an additional documentation and can be
interpreted by IDEs and static analysis tools to improve code analysis.
## Using the annotations
The annotations are published on [Maven Central](http://repo1.maven.org/maven2/org/jetbrains/annotations/) and [JCenter](https://jcenter.bintray.com/org/jetbrains/annotations/). To add a dependency
using gradle write the following in `build.gradle` file:
```
dependencies {
compile 'org.jetbrains:annotations:16.0.2'
}
```
To add a dependency using Maven write the following in `pom.xml`:
```xml
<dependency>
<groupId>org.jetbrains</groupId>
<artifactId>annotations</artifactId>
<version>16.0.2</version>
</dependency>
```
`annotations` artifact require JDK 1.8 or higher. If your project is compiled using JDK 1.5, 1.6 or 1.7 you can use
`annotations-java5` artifact instead.
build.gradle 0 → 100644
View file @ 8d517251
buildscript {
repositories {
jcenter()
}
dependencies {
classpath 'com.jfrog.bintray.gradle:gradle-bintray-plugin:1.7.3'
}
}
ext.projectVersion = projectVersion
if (System.getenv('BINTRAY_USER') == null) {
ext.projectVersion = ext.projectVersion + '-SNAPSHOT'
}
allprojects {
group 'org.jetbrains'
version rootProject.ext.projectVersion
}
subprojects {
apply plugin: 'java'
apply plugin: 'maven-publish'
apply plugin: 'com.jfrog.bintray'
repositories {
mavenCentral()
}
}
project(':java5').archivesBaseName = 'annotations-java5'
project(':java8').archivesBaseName = 'annotations'
configure([project(':java5'), project(':java8')]) {
dependencies {
compile project(':common')
}
task mainJar(type: Jar) {
from sourceSets.main.output
from project(':common').sourceSets.main.output
}
task sourceJar(type: Jar) {
from sourceSets.main.java
from project(':common').sourceSets.main.java
baseName = archivesBaseName + '-sources'
}
javadoc {
source = [sourceSets.main.java, project(':common').sourceSets.main.java]
}
task javadocJar(type: Jar) {
from javadoc
}
artifacts {
archives mainJar, sourceJar
}
publishing {
publications {
mavenJava(MavenPublication) {
artifactId archivesBaseName
artifact mainJar
artifact sourceJar {
classifier 'sources'
}
artifact javadocJar {
classifier 'javadoc'
}
pom.withXml {
asNode().children().last() + {
resolveStrategy = DELEGATE_FIRST
name 'JetBrains Java Annotations'
description 'A set of annotations used for code inspection support and code documentation.'
url 'https://github.com/JetBrains/java-annotations'
scm {
url 'https://github.com/JetBrains/java-annotations'
connection 'scm:git:git://github.com/JetBrains/java-annotations.git'
developerConnection 'scm:git:ssh://github.com:JetBrains/java-annotations.git'
}
licenses {
license {
name 'The Apache Software License, Version 2.0'
url 'http://www.apache.org/license/LICENSE-2.0.txt'
distribution 'repo'
}
}
developers {
developer {
id 'JetBrains'
name 'JetBrains Team'
organization 'JetBrains'
organizationUrl 'https://www.jetbrains.com'
}
}
}
}
}
}
}
if (System.getenv('BINTRAY_USER') != null) {
bintray {
user = System.getenv('BINTRAY_USER')
key = System.getenv('BINTRAY_KEY')
publish = true
publications = ['mavenJava']
pkg {
userOrg = 'jetbrains'
repo = 'intellij-redist'
name = 'org.jetbrains:' + archivesBaseName
version {
name = rootProject.ext.projectVersion
}
}
}
}
}
common/build.gradle 0 → 100644
View file @ 8d517251
sourceCompatibility = 1.5
common/src/main/java/org/intellij/lang/annotations/Flow.java 0 → 100644
View file @ 8d517251
/*
* Copyright 2000-2015 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.
* 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 org.intellij.lang.annotations;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
* 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)})
* or from the container to the method return value (e.g. {@code Set.toArray()})
* or between method parameters (e.g. {@code System.arraycopy(array1, 0, array2, length)})
*/
@Retention(RetentionPolicy.CLASS)
@Target({ElementType.PARAMETER, ElementType.METHOD})
public @interface Flow {
/**
* Denotes the source of the data flow.<br>
* Allowed values are:<br>
*
* <ul>
* <li>{@code THIS_SOURCE} - Means that the data flows from this container.<br>
* E.g. annotation for java.util.List method get(index) means the method reads contents of list and returns it.<br>
* {@code @Flow(source = THIS_SOURCE) T get(int index);}<br>
* </li>
* <li>
* {@code this.}Field name - means that the data flows from this container some (synthetic) field.<br>
* E.g. annotation for java.util.Map.keySet() method here means that it returns data from the map from the field named "keys".<br>
* {@code @Flow(source = "this.keys") Set<K> keySet();}
* </li>
* </ul>
* By default, the source() value is:<br>
* <ul>
* <li>
* {@link #THIS_SOURCE} if the method was annotated, e.g.<br>
* {@code @Flow(sourceIsContainer=true, targetIsContainer=true) Object[] Collection.toArray()}<br>
* Here the annotation tells us that java.util.Collection.toArray() method<br>
* reads the contents of this collection (source=THIS_SOURCE by default) and passes it outside.
* </li>
* <li>
* Corresponding argument if the method parameter was annotated, e.g.<br>
* {@code void List.add(@Flow(targetIsContainer=true) E item)}<br>
* Here the annotation tells us that java.util.List.add(E item) method<br>
* takes the argument (source="item" by default) and passes it to this collection.
* </li>
* </ul>
*/
String source() default Flow.DEFAULT_SOURCE;
String DEFAULT_SOURCE = "The method argument (if parameter was annotated) or this container (if instance method was annotated)";
String THIS_SOURCE = "this";
/**
* 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>
* ArrayList(<pre><tt>{@code @Flow(sourceIsContainer=true, targetIsContainer=true) Collection<? extends E> collection }</tt></pre>) <br>
* By default it's false.
*/
boolean sourceIsContainer() default false;
/**
* Denotes the destination of the data flow.<br>
* Allowed values are:<br>
*
* <ul>
* <li>{@code THIS_TARGET} - Means that the data flows inside this container (of the class the annotated method belongs to).<br>
* E.g. annotation for java.util.List method add(element) means the method takes the argument and passes it to this collection.<br>
* {@code boolean add(@Flow(target=THIS_TARGET, targetIsContainer=true) E element);}<br>
* </li>
* <li>
* Parameter name - means the data flows to this parameter.<br>
* E.g.<br>
* {@code void arraycopy(@Flow(sourceIsContainer=true, target="dest", targetIsContainer=true) Object src, int srcPos, Object dest, int destPos, int length)}<br>
* means that java.lang.System.arraycopy() method takes its first argument and passes it to the "dest" parameter.
* </li>
* <li>
* {@code this.}Field name - means that the data flows to this container in some (synthetic) field.<br>
* E.g. annotation for java.util.Map.put(key, value) method here means that it takes the argument 'key' and stores the data in some (hidden) field named "keys".<br>
* {@code V put(@Flow(target = "this.keys", targetIsContainer=true) K key, V value);}
* </li>
* </ul>
* By default, the target() value is:<br>
* <ul>
* <li>
* {@link #THIS_TARGET} if the parameter was annotated, e.g.<br>
* {@code void List.set(int index, @Flow(targetIsContainer=true) E element)}<br>
* Here the annotation tells us that java.util.List.set(index, element) method<br>
* reads its second argument 'element' and passes it to this collection (target=THIS_TARGET by default).
* </li>
* <li>
* {@link #RETURN_METHOD_TARGET} if the method was annotated, e.g.:<br>
* {@code @Flow(sourceIsContainer=true) E List.remove(int index)}<br>
* Here the annotation tells us that java.util.List.remove(int index) method<br>
* returns the data from its collection (target=RETURN_METHOD_TARGET by default).
* </li>
* </ul>
*/
String target() default Flow.DEFAULT_TARGET;
String DEFAULT_TARGET = "This container (if the parameter was annotated) or the return value (if instance method was annotated)";
String RETURN_METHOD_TARGET = "The return value of this method";
String THIS_TARGET = "this";
/**
* true if the data target is container and we should track not the expression but its contents.<br>
* E.g. the java.lang.System.arraycopy() method parameter 'dest' is actually an array:<br>
* {@code void arraycopy(@Flow(sourceIsContainer=true, target="dest", targetIsContainer=true) Object src, int srcPos, Object dest, int destPos, int length)}<br>
* By default it's false.
*/
boolean targetIsContainer() default false;
}
org/intellij/lang/annotations/JdkConstants.java → common/src/main/java/org/intellij/lang/annotations/JdkConstants.java
View file @ 8d517251
......@@ -40,6 +40,18 @@ public class JdkConstants {
@MagicConstant(intValues = {Adjustable.HORIZONTAL, Adjustable.VERTICAL})
public @interface AdjustableOrientation {}
@MagicConstant(intValues = {
ScrollPaneConstants.VERTICAL_SCROLLBAR_AS_NEEDED,
ScrollPaneConstants.VERTICAL_SCROLLBAR_ALWAYS,
ScrollPaneConstants.VERTICAL_SCROLLBAR_NEVER})
public @interface VerticalScrollBarPolicy {}
@MagicConstant(intValues = {
ScrollPaneConstants.HORIZONTAL_SCROLLBAR_AS_NEEDED,
ScrollPaneConstants.HORIZONTAL_SCROLLBAR_ALWAYS,
ScrollPaneConstants.HORIZONTAL_SCROLLBAR_NEVER})
public @interface HorizontalScrollBarPolicy {}
@MagicConstant(intValues = {Calendar.JANUARY, Calendar.FEBRUARY, Calendar.MARCH, Calendar.APRIL, Calendar.MAY, Calendar.JUNE, Calendar.JULY, Calendar.AUGUST, Calendar.SEPTEMBER, Calendar.OCTOBER, Calendar.NOVEMBER, Calendar.DECEMBER})
public @interface CalendarMonth {}
......
org/intellij/lang/annotations/Language.java → common/src/main/java/org/intellij/lang/annotations/Language.java
View file @ 8d517251
......@@ -18,11 +18,12 @@ package org.intellij.lang.annotations;
import org.jetbrains.annotations.NonNls;
import static java.lang.annotation.ElementType.*;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import static java.lang.annotation.ElementType.*;
@Retention(RetentionPolicy.CLASS)
@Target({ METHOD, FIELD, PARAMETER, LOCAL_VARIABLE, ANNOTATION_TYPE })
......
org/intellij/lang/annotations/MagicConstant.java → common/src/main/java/org/intellij/lang/annotations/MagicConstant.java
View file @ 8d517251
/*
* 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.
......@@ -18,11 +18,11 @@ package org.intellij.lang.annotations;
import java.lang.annotation.*;
/**
* <p>This annotation intended to help IDEA to detect and auto-complete int and String constants used as an enumeration.
* <p>This annotation intended to help IntelliJ IDEA and other IDEs to detect and auto-complete int and String constants used as an enumeration.
* For example, in the {@link java.awt.Label#Label(String, int)} constructor the <tt><b>alignment</b></tt> parameter can be one of the following
* int constants: {@link java.awt.Label#LEFT}, {@link java.awt.Label#CENTER} or {@link java.awt.Label#RIGHT}
*
* <p>So, if <tt>@MagicConstant</tt> annotation applied to this constructor, IDEA will check the constructor usages for the allowed values.
* <p>So, if <tt>@MagicConstant</tt> annotation applied to this constructor, the IDE will check the constructor usages for the allowed values.
* <p>E.g.<br>
* <pre>{@code
* new Label("text", 0); // 0 is not allowed
......@@ -38,7 +38,7 @@ import java.lang.annotation.*;
* <pre>{@code @MagicConstant(intValues = {TOP, CENTER, BOTTOM})
* int textPosition;
* }</pre>
* IDEA will check expressions assigned to the variable for allowed values:
* The IDE will check expressions assigned to the variable for allowed values:
* <pre>{@code
* textPosition = 0; // not allowed
* textPosition = TOP; // OK
......@@ -51,7 +51,7 @@ import java.lang.annotation.*;
* public native int getModifiers();
* }</pre>
*
* IDEA will analyse getModifiers() method calls and check if its return value is used with allowed values:<br>
* The IDE will analyse getModifiers() method calls and check if its return value is used with allowed values:<br>
* <pre>{@code
* if (aClass.getModifiers() == 3) // not allowed
* if (aClass.getModifiers() == Modifier.PUBLIC) // OK
......@@ -65,10 +65,9 @@ import java.lang.annotation.*;
* <pre>{@code @MagicConstant(flags = {Font.PLAIN, Font.BOLD, Font.ITALIC}) }</pre>
* <pre>{@code @interface FontStyle {} }</pre>
*
* IDEA will check constructs annotated with @FontStyle for allowed values:<br>
* The IDE will check constructs annotated with @FontStyle for allowed values:<br>
* <tt>@FontStyle int myStyle = 3; // not allowed<br></tt>
* <tt>@FontStyle int myStyle = Font.BOLD | Font.ITALIC; // OK</tt><br>
* </tt>
*
* </ul>
*
......@@ -84,10 +83,11 @@ public @interface MagicConstant {
/**
* @return int values (typically named constants) which are allowed here.
* E.g.
* <tt>
* <pre><tt>
* {@code
* void setConfirmOpenNewProject(@MagicConstant(intValues = {OPEN_PROJECT_ASK, OPEN_PROJECT_NEW_WINDOW, OPEN_PROJECT_SAME_WINDOW})
* int confirmOpenNewProject);
* </tt>
* }</tt></pre>
*/
long[] intValues() default {};
......@@ -97,16 +97,18 @@ public @interface MagicConstant {
String[] stringValues() default {};
/**
* @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.
* @return allowed int flags (i.e. values (typically named constants) which can be combined with bitwise OR operator (|).
* The difference from the {@link #intValues()} is that flags are allowed to be combined (via plus:+ or bitwise OR: |) whereas values aren't.
* The literals "0" and "-1" are also allowed to denote absence and presense of all flags respectively.
*
* E.g.
* <tt>
* @MagicConstant(flags = {HierarchyEvent.PARENT_CHANGED,HierarchyEvent.DISPLAYABILITY_CHANGED,HierarchyEvent.SHOWING_CHANGED})
* <pre><tt>
* {@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>
* hFlags = 3; // not allowed; should be "magic" constant.
* if (hFlags & (HierarchyEvent.PARENT_CHANGED | HierarchyEvent.SHOWING_CHANGED) != 0); // OK: combined several constants via bitwise OR
* }</tt></pre>
*/
long[] flags() default {};
......@@ -114,27 +116,29 @@ public @interface MagicConstant {
* @return allowed values which are defined in the specified class public static final constants.
*
* E.g.
* <tt>
* @MagicConstant(valuesFromClass = Cursor.class)
* <pre><tt>
* {@code @MagicConstant(valuesFromClass = Cursor.class)
* int cursorType;
*
* cursorType = 11; // not allowed;
* cursorType = Cursor.E_RESIZE_CURSOR; // OK
* </tt>
* cursorType = 11; // not allowed; should be "magic" constant.
* cursorType = Cursor.E_RESIZE_CURSOR; // OK: "magic" constant used.
* }</tt></pre>
*/
Class valuesFromClass() default void.class;
/**
* @return allowed int flags which are defined in the specified class public static final constants.
* The difference from the {@link #valuesFromClass()} is that flags are allowed to be combined (via plus:+ or bitwise OR: |) whereas values aren't.
* The literals "0" and "-1" are also allowed to denote absence and presense of all flags respectively.
*
* E.g.
* <tt>@MagicConstant(flagsFromClass = java.awt.InputEvent.class)
* <pre><tt>
* {@code @MagicConstant(flagsFromClass = java.awt.InputEvent.class)
* int eventMask;
*
* eventMask = 10; // not allowed;
* eventMask = InputEvent.CTRL_MASK | InputEvent.ALT_MASK; // OK
* </tt>
* eventMask = 10; // not allowed; should be "magic" constant.
* eventMask = InputEvent.CTRL_MASK | InputEvent.ALT_MASK; // OK: combined several constants via bitwise OR
* }</tt></pre>
*/
Class flagsFromClass() default void.class;
}
common/src/main/java/org/jetbrains/annotations/Async.java 0 → 100644
View file @ 8d517251
// Copyright 2000-2018 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file.
package org.jetbrains.annotations;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
* Helper annotations for asynchronous computation.
* Used for example in IntelliJ IDEA's debugger for async stacktraces feature.
*
* @author egor
*/
public interface Async {
/**
* Indicates that the marked method schedules async computation.
* Scheduled object is either {@code this}, or the annotated parameter value.
*/
@Retention(RetentionPolicy.CLASS)
@Target({ElementType.METHOD, ElementType.CONSTRUCTOR, ElementType.PARAMETER})
@interface Schedule {}
/**
* Indicates that the marked method executes async computation.
* Executed object is either {@code this}, or the annotated parameter value.
* This object needs to match with the one annotated with {@link Schedule}
*/
@Retention(RetentionPolicy.CLASS)
@Target({ElementType.METHOD, ElementType.CONSTRUCTOR, ElementType.PARAMETER})
@interface Execute {}
}
common/src/main/java/org/jetbrains/annotations/Contract.java 0 → 100644
View file @ 8d517251
/*
* Copyright 2000-2016 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.
* 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 org.jetbrains.annotations;
import java.lang.annotation.*;
import java.util.concurrent.atomic.AtomicBoolean;
/**
* Specifies some aspects of the method behavior depending on the arguments. Can be used by tools for advanced data flow analysis.
* Note that this annotation just describes how the code works and doesn't add any functionality by means of code generation.<p>
*
* Method contract has the following syntax:<br>
* <pre>{@code
* contract ::= (clause ';')* clause
* clause ::= args '->' effect
* args ::= ((arg ',')* arg )?
* arg ::= value-constraint
* value-constraint ::= '_' | 'null' | '!null' | 'false' | 'true'
* effect ::= value-constraint | 'fail' | 'this' | 'new' | 'param<N>'}</pre> <p>
*
* The constraints denote the following:<br>
* <ul>
* <li> _ - any value
* <li> null - null value
* <li> !null - a value statically proved to be not-null
* <li> true - true boolean value
* <li> false - false boolean value
* </ul>
*
* The additional return values denote the following:<br>
* <ul>
* <li> fail - the method throws an exception, if the arguments satisfy argument constraints
* <li> new - (supported in IntelliJ IDEA since version 2018.2) the method returns a non-null new object which is distinct from any other object existing in the heap prior to method execution. If method is also pure, then we can be sure that the new object is not stored to any field/array and will be lost if method return value is not used.
* <li> this - (supported in IntelliJ IDEA since version 2018.2) the method returns its qualifier value (not applicable for static methods)
* <li> param1, param2, ... - (supported in IntelliJ IDEA since version 2018.2) the method returns its first (second, ...) parameter value
* </ul>
* Examples:<p>
* {@code @Contract("_, null -> null")} - the method returns null if its second argument is null<br>
* {@code @Contract("_, null -> null; _, !null -> !null")} - the method returns null if its second argument is null and not-null otherwise<br>
* {@code @Contract("true -> fail")} - a typical {@code assertFalse} method which throws an exception if {@code true} is passed to it<br>
* {@code @Contract("_ -> this")} - the method always returns its qualifier (e.g. {@link StringBuilder#append(String)}).
* {@code @Contract("null -> fail; _ -> param1")} - the method throws an exception if the first argument is null,
* otherwise it returns the first argument (e.g. {@code Objects.requireNonNull}).<br>
* {@code @Contract("!null, _ -> param1; null, !null -> param2; null, null -> fail")} - the method returns the first non-null argument,
* or throws an exception if both arguments are null (e.g. {@code Objects.requireNonNullElse} in Java 9).<br>
*
*/
@Documented
@Retention(RetentionPolicy.CLASS)
@Target({ElementType.METHOD, ElementType.CONSTRUCTOR})
public @interface Contract {
/**
* Contains the contract clauses describing causal relations between call arguments and the returned value
*/
String value() default "";
/**
* Specifies that the annotated method has no visible side effects.
* If its return value is not used, removing its invocation won't
* affect program state and change the semantics, unless method call throws an exception.
* Exception throwing is not considered to be a side effect.
* <p>
* Method should not be marked as pure if it does not produce a side-effect by itself,
* but it could be used to establish a happens-before relation between an event in
* another thread, so changes performed in another thread might become visible in current thread
* after this method invocation. Examples of such methods are {@link Object#wait()}, {@link Thread#join()}
* or {@link AtomicBoolean#get()}. On the other hand, some synchronized methods like {@link java.util.Vector#get(int)}
* could be marked as pure, because the purpose of synchronization here is to keep the collection internal integrity
* rather than to wait for an event in another thread.
* <p>
* "Invisible" side effects (such as logging) that don't affect the "important" program semantics are allowed.<br><br>
* <p>
* 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;
/**
* Contains a specifier which describes which method parameters can be mutated during the method call.
* <p>
* The following values are possible:
* <table summary="">
* <tr><td>"this"</td><td>Method mutates the receiver object, and doesn't mutates any objects passed as arguments (cannot be applied for static method or constructor)</td></tr>
* <tr><td>"param"</td><td>Method mutates the sole argument and doesn't mutate the receiver object (if applicable)</td></tr>
* <tr><td>"param1", "param2", ...</td><td>Method mutates the N-th argument</td></tr>
* <tr><td>"this,param1"</td><td>Method mutates the receiver and first argument and doesn't mutate any other arguments</td></tr>
* </table>
*
* <strong>Warning: This annotation parameter is experimental and may be changed or removed without further notice!</strong>
* @return a mutation specifier string
*/
String mutates() default "";
}
org/jetbrains/annotations/Nls.java → common/src/main/java/org/jetbrains/annotations/Nls.java
View file @ 8d517251
/*
* Copyright 2000-2009 JetBrains s.r.o.
* Copyright 2000-2015 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.
......@@ -19,15 +19,30 @@ package org.jetbrains.annotations;
import java.lang.annotation.*;
/**
* Specifies that an element of the program is a user-visible string which needs to be localized,
* or does not contain such strings. The annotation is intended to be used by localization tools for
* detecting strings which should be reported as requiring localization. Generally, this doesn't change
* IDEA's behaviour - it's just a markup, showing that the string was verified is indeed localizable.
* Specifies that an element of the program is an user-visible string which needs to be localized.
* This annotation is intended to be used by localization tools for
* detecting strings which should be reported as requiring localization.
*
* @author mike
* @see NonNls
*/
@Documented
@Retention(RetentionPolicy.CLASS)
@Target({ElementType.METHOD, ElementType.FIELD, ElementType.PARAMETER, ElementType.LOCAL_VARIABLE, ElementType.TYPE, ElementType.PACKAGE})
public @interface Nls {
enum Capitalization {
NotSpecified,
/**
* e.g. This Is a Title
*/
Title,
/**
* e.g. This is a sentence
*/
Sentence
}
Capitalization capitalization() default Capitalization.NotSpecified;
}
org/jetbrains/annotations/NonNls.java → common/src/main/java/org/jetbrains/annotations/NonNls.java
View file @ 8d517251
......@@ -19,33 +19,34 @@ package org.jetbrains.annotations;
import java.lang.annotation.*;
/**
* Specifies that an element of the program is not a user-visible string which needs to be localized,
* or does not contain such strings. The annotation is intended to be used by localization tools for
* Specifies that an element of the program is not an user-visible string which needs to be localized,
* or does not contain such strings. This annotation is intended to be used by localization tools for
* detecting strings which should not be reported as requiring localization.
* <ul>
* <li>If a method parameter is annotated with <code>NonNls</code>, the strings passed
* <li>If a method parameter is annotated with {@code NonNls}, the strings passed
* as values of this parameter are not reported as requiring localization.
* Also, if the parameter of a property setter method is annotated with <code>NonNls</code>, values
* Also, if the parameter of a property setter method is annotated with {@code NonNls}, values
* of that property in UI Designer forms are never highlighted as hard-coded strings.</li>
* <li>If a field is annotated with <code>NonNls</code>, all string literals found in the
* <li>If a field is annotated with {@code NonNls}, all string literals found in the
* initializer of the field are not reported as requiring localization.</li>
* <li>If a method is called on a field, parameter or local variable annotated with <code>NonNls</code>,
* <li>If a method is called on a field, parameter or local variable annotated with {@code NonNls},
* string literals passed as parameters to the method are not reported as requiring localization.
* <li>If a field, parameter or local variable annotated with <code>NonNls</code> is passed as a
* parameter to the <code>equals()</code> method invoked on a string literal, the literal is not
* <li>If a field, parameter or local variable annotated with {@code NonNls} is passed as a
* parameter to the {@code equals()} method invoked on a string literal, the literal is not
* reported as requiring localization.</li>
* <li>If a field, parameter or local variable annotated with <code>NonNls</code> is found at
* <li>If a field, parameter or local variable annotated with {@code NonNls} is found at
* the left side of an assignment expression, all string literals in the right side
* of the expression are not reported as requiring localization.</li>
* <li>If a method is annotated with <code>NonNls</code>, string literals returned from the method
* <li>If a method is annotated with {@code NonNls}, string literals returned from the method
* are not reported as requiring localization.</li>
* <li>If a class is annotated with <code>NonNls</code>, all string literals in
* <li>If a class is annotated with {@code NonNls}, all string literals in
* the class and all its subclasses are not reported as requiring localization.</li>
* <li>If a package is annotated with <code>NonNls</code>, all string literals in
* <li>If a package is annotated with {@code NonNls}, all string literals in
* the package and all its subpackages are not reported as requiring localization.</li>
* </ul>
*
* @author max
* @see Nls
*/
@Documented
@Retention(RetentionPolicy.CLASS)
......
org/jetbrains/annotations/TestOnly.java → common/src/main/java/org/jetbrains/annotations/TestOnly.java
View file @ 8d517251
/*
* Copyright 2000-2012 JetBrains s.r.o.
* Copyright 2000-2015 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.
......@@ -13,19 +13,17 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.jetbrains.annotations;
import java.lang.annotation.*;
/**
* A method/constructor annotated with TestOnly claims that it should be called from testing code only.
* <p/>
* <p>
* Apart from documentation purposes this annotation is intended to be used by static analysis tools
* to validate against element contract violations.
*/
@Documented
@Retention(RetentionPolicy.SOURCE)
@Target({ElementType.METHOD, ElementType.CONSTRUCTOR})
public @interface TestOnly {
}
@Target({ElementType.METHOD, ElementType.CONSTRUCTOR, ElementType.FIELD, ElementType.TYPE})
public @interface TestOnly { }
\ No newline at end of file