Merge branch 'main' into gradle-action

.github/workflows/build.yml

@@ -22,7 +22,7 @@ jobs:
     continue-on-error: ${{ matrix.experimental }}
     steps:
       - uses: actions/checkout@v4
-      - uses: gradle/wrapper-validation-action@v2
+      - uses: gradle/wrapper-validation-action@v3
       - name: Set up JDK ${{ matrix.java_version }}
         uses: actions/setup-java@v4
         with:

.github/workflows/docs.yml

@@ -46,7 +46,7 @@ jobs:
           name: document
           path: docs/build
 
-      - uses: JamesIves/github-pages-deploy-action@4.1.5
+      - uses: JamesIves/github-pages-deploy-action@v4.6.1
         with:
           branch: gh-pages
           folder: docs/build

build.gradle

@@ -1,3 +1,19 @@
+/**
+ * Copyright 2020 The JSpecify Authors.
+ *
+ * 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.
+ */
+
 plugins {
     id 'java-library'
     id 'io.github.gradle-nexus.publish-plugin' version '1.3.0' apply false

conformance-tests/build.gradle

@@ -1,3 +1,19 @@
+/**
+ * Copyright 2023 The JSpecify Authors.
+ *
+ * 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.
+ */
+
 import org.gradle.api.JavaVersion
 
 plugins {

docs/docs/user-guide.md

@@ -124,8 +124,10 @@ class Example {
 The `@NullMarked` annotation indicates that references can't be null in its
 scope, unless their types are explicitly marked `@Nullable`. If applied to a
 module then its scope is all the code in the module. If applied to a package
-then its scope is all the code in the package. If applied to a class or
-interface then its scope is all the code in that class or interface.
+then its scope is all the code in the package. (Note that packages are _not_
+hierarchical; applying `@NullMarked` to package `com.foo` does not make package
+`com.foo.bar` `@NullMarked`.)  If applied to a class or interface then its scope
+is all the code in that class or interface.
 
 Outside `@NullMarked`, `@Nullable String` still means a reference that can be
 null, but JSpecify doesn't have anything to say about whether plain `String` can