Debian Codegraph @

src/main/java/org/jspecify/annotations/package-info.java

raw
1 /*
2 * Copyright 2022 The JSpecify Authors.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 /**
18 * JSpecify annotations. See <a href="http://jspecify.org">jspecify.org</a> for general information.
19 *
20 * <h2>What's here?</h2>
21 *
22 * This package will contain annotations supporting a variety of static analyses. For now it
23 * supports just nullness analysis.
24 *
25 * <h3 id="nullness">Nullness</h3>
26 *
27 * The primary annotations of interest are {@link NullMarked} and {@link Nullable}. Together they
28 * provide <b>declarative, use-site nullness</b> for Java types. Less frequently, their negations
29 * may be useful: {@link NullUnmarked} and {@link NonNull}, respectively.
30 *
31 * <p>For a comprehensive introduction to JSpecify, please see <a
32 * href="http://jspecify.org">jspecify.org</a>.
33 *
34 * <h2 id="tool-behavior">Note on tool behavior</h2>
35 *
36 * <p>Each of these annotations defines a single meaning shared by all compatible tools (and
37 * libraries). JSpecify documentation aims to provide unambiguous, tool-independent answers for how
38 * to properly annotate your APIs in all circumstances. However, tools are permitted to
39 * <i>respond</i> to the information you provide however they see fit (or not at all). JSpecify
40 * compatibility does not require that any particular finding must or must not be issued to the
41 * user, let alone its message or severity.
42 *
43 * <p>In fact, it's important to remember that declarative annotations are merely <i>one</i> source
44 * of information an analyzer may consult in concluding an expression is safely non-null. Just like
45 * one analyzer might determine that an {@code int} expression can take on only positive values,
46 * another might likewise determine that a declaratively nullable expression can take on only
47 * non-null values. In both cases the declarative knowledge is <i>correct</i>, but the inferred
48 * knowledge is both correct and more specific.
49 *
50 * <p>On the other end, the tools might even enforce <i>nothing at all</i>. In particular, your
51 * annotated code (or other code dependent on its annotated APIs) might be compiled and run without
52 * any appropriate tool even in use. Therefore adopting JSpecify annotations is not a replacement
53 * for <b>explicitly checking arguments</b> at runtime.
54 */
55 package org.jspecify.annotations;