Debian Codegraph @

samples/README.md

raw
1 # Sample inputs
2
3 Currently, the main purpose of these samples is to act as a source of test cases
4 for authors of nullness checkers that wish to use JSpecify nullness information.
5
6 ## Disclaimers
7
8 These sample inputs are informative, not normative.
9
10 They use annotations whose names and meanings are not finalized. Notably, they
11 currently use an explicit `@NullnessUnspecified` annotation, even though that
12 annotation was not part of our 0.1 milestone and will quite possibly not be part
13 of our 1.0 release. (Still, we haven't yet removed the `@NullnessUnspecified`
14 usages: First, we're not yet certain whether we'll include that annotation or
15 not. Second, the annotation provides an easier way to demonstrate rules that can
16 arise without it but are easier to demonstrate with it. We probably wouldn't
17 write such samples if we were starting from scratch today, but we wrote them
18 when we started, and they appear to provide some value on net.)
19
20 They have mostly not been code reviewed.
21
22 We do not know if this is even the format that we want our sample inputs to be
23 in.
24
25 Whatever our final samples look like, we do **not** expect to present them as
26 "conformance tests" that require any behavior from tools:
27
28 - JSpecify nullness information may be of use to many kinds of tools, not just
29 "nullness checkers." But these samples are written in a way that makes them
30 most useful to authors of nullness checkers. Authors of other tools -- those
31 that render API descriptions, generate source code, perform refactorings,
32 etc. -- are not best served by the samples' focus on
33 `jspecify_nullness_mismatch`, etc.
34
35 - The goal of JSpecify is to provide one source of nullness information. Tools
36 may use some, all, or none of that information. They may also use
37 information from other sources.
38
39 - Some examples of "information from other sources":
40
41 - looking at the *implementation* of a method to decide whether it can
42 return `null`
43 - looking at non-JSpecify nullness annotations in code
44 - looking at "overlay" or "stub" information about nullness for
45 well-known APIs
46 - looking at whether the parameter to a call to `Map.get` is known to
47 be present in that map
48 - defining a rule to treat all unannotated type usages the same, when
49 the JSpecify rules give some of them "unspecified nullness"
50
51 - Based on the information they have available for any given piece of code,
52 tools always have the option to issue a warning / error / other diagnostic
53 for that code, and they always have the option not to. (Even for a tool that
54 uses *all* JSpecify information and *only* JSpecify information, that
55 information is, at its heart, *information* for tools to apply as their
56 authors see fit.)
57
58 ## Syntax
59
60 <!-- TODO: Update links to point to the markup-format spec and glossary. -->
61
62 A special comment on a given line of a `.java` file provides information about
63 the following line.
64
65 The first three special comments indicate that JSpecify annotations are applied
66 in ways that are
67 [unrecognized](http://jspecify.org/spec#recognized-locations-type-use). Tools
68 are likely to report an error in the case of the first two, somewhat less likely
69 to report an error in the case of the third (since they might choose to give
70 their meaning to annotations there), and not *obligated* to do anything for any
71 of the cases:
72
73 - `jspecify_conflicting_annotations`: for cases like `@Nullable
74 @NullnessUnspecified Foo`
75
76 - `jspecify_nullness_intrinsically_not_nullable`: for cases like `@Nullable
77 int`
78
79 - `jspecify_unrecognized_location`: for the other cases in which JSpecify does
80 not give meaning to an annotation, like `class @Nullable Foo {}`.
81
82 The last two comments indicate a nullness violation: an inconsistency between
83 two annotations, or between annotations and source code. You can think of these
84 as extending the normal JLS type rules to cover types that have been augmented
85 with nullness information. (For example, the value of a `return` statement must
86 be convertible to the method's return type, and the receiver in a method call
87 should not be `@Nullable`.) Nullness checkers are likely to report an error for
88 each `jspecify_nullness_mismatch` comment, are likely to make many different
89 decisions in whether to issues a diagnostic (error, warning, or no diagnostic)
90 for any particular `jspecify_nullness_not_enough_information` comment, and are
91 not *obligated* to do anything for any particular comment. (For some background
92 on that, see the disclaimers above. Also, note that a nullness checker can be
93 sound even if it does not issue errors for some cases of
94 `jspecify_nullness_mismatch` or `jspecify_nullness_not_enough_information`!)
95
96 - `jspecify_nullness_mismatch`
97
98 - `jspecify_nullness_not_enough_information`: for nullness violations that
99 involve
100 [unspecified nullness](https://docs.google.com/document/d/1KQrBxwaVIPIac_6SCf--w-vZBeHkTvtaqPSU_icIccc/edit#bookmark=id.xb9w6p3ilsq3).
101
102 TODO: Consider additional features:
103
104 - multiline comments
105 - other locations for comments
106 - multiple findings per line/comment
107 - comments that apply to larger ranges -- possibly to syntax elements (like
108 statements) rather than lines
109 - comments that apply only to a particular part of the line
110
111 ## Directory structure
112
113 See
114 [JSpecify: test-data format: Directory structure](https://docs.google.com/document/d/1JVH2p61kReO8bW4AKnbkpybPYlUulVmyNrR1WRIEE_k/edit#bookmark=id.2t1r58i5a03s).
115 TODO(#134): Inline that here if Tagir can sign the CLA and contribute it.
116
117 Additionally:
118
119 Fully qualified class names must be unique across all directories.
120
121 > This permits all files to be compiled in a single tool invocation.
122
123 TODO: Consider requiring that all individual-file samples be in the top-level
124 directory.
125
126 Each file must contain a single top-level class. TODO(#133): Consider relaxing
127 this.
128
129 TODO: Consider requiring a file's path to match its package and class:
130
131 - individual-file samples: `Foo.java` for `Foo`
132
133 - full-directory samples: `sampleFoo/Foo.java` for `Foo`,
134 `sampleFoo/bar/Foo.java` for `bar.Foo`
135
136 - We may need additional accommodations for JPMS support to demonstrate
137 module-level defaulting.
138
139 ## Restrictions
140
141 Files must be UTF-8 encoded.
142
143 Files must contain only printable ASCII characters and `\n`.
144
145 Files must be compatible with Java 8. TODO(#131): Decide how to label files that
146 require a higher version so that we can allow them. (But still encourage
147 sticking to Java 8 except for tests that specifically exercise newer features.)
148
149 Files must compile without error using stock javac.
150
151 Files must not depend on any classes other than the JSpecify annotations. This
152 includes the Java platform APIs. Exception: Files may use `java.lang.Object`,
153 but they still must not use its methods.
154
155 > For example, files may use `Object` as a bound, parameter, or return type.
156
157 Files should avoid depending on the presence of absence of "smart" checker
158 features, such as:
159
160 - looking inside the body of a method to determine what parameters it
161 dereferences or what it returns
162
163 - To that end, prefer abstract methods when practical.
164
165 - flow-sensitive typing
166
167 We also encourage writing files that demonstrate individual behaviors in
168 isolation. For example, we encourage writing files to minimize how much they
169 rely on type inference -- except, of course, for any files explicitly intended
170 to demonstrate type inference.
171
172 ## More TODOs
173
174 TODO: Consider how to map between samples and related GitHub issues (comments,
175 filenames?).