Updates docs for ScanOption

CHANGELOG.md

@@ -13,6 +13,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- `forPackage(String packageName, ScanOption... option)` overload. This provides a more consistent way to fine-tune the scanning of packages. `ScanOption` provides several features, which can be mixed and matched:
+  - `ScanOption.recursive()` to search recursively. This replaces `forPackage(String packageName, boolean scanRecursively)`.
+  - `ScanOption.mustExtend(Class<?> type)` to find only classes that extend or implement the given type. This replaces `forPackage(String packageName, Class<?> mustExtend)`. Note that this overload used to search recursively too; this is no longer the case. If you want a recursive search that also only matches subtypes, you have to combine `ScanOption.recursive()` and `ScanOption.mustExtend(Class<?> type)`.
+  - `ScanOption.except(Class<?>... types)` to find all classes except the given ones. This replaces `forPackage(...).except(Class<?>... types)`.
+  - `ScanOption.except(Predicate<Class<?>> exclusionPredicate)` to exclude all classes that match the given predicate. This replaces `forPackage(...).except(Predicate<Class<?>> exclusionPredicate)`.
+  - `ScanOption.ignoreExternalJars()` to not throw an exception when attempting to scan a package from a third-party jar file. This can be useful if you have a split package between a dependency and your own codebase. This is a new option. ([Issue 1040](https://github.com/jqno/equalsverifier/issues/1040))
+
+### Deprecated
+
+- `forPackage(String packageName, boolean scanRecursively)`: replaced by `ScanOption.recursive()`.
+- `forPackage(String packageName, Class<?> mustExtend)`: replaced by `ScanOption.mustExtend(Class<?> type)` combined with `ScanOption.recursive()`.
+- `forPackage(...).except(Class<?>... types)`: replaced by `ScanOption.except(Class<?>... type)`.
+- `forPackage(...).except(Predicate<Class<?>>... exclusionPredicate)`: replaced by `ScanOption.except(Predicate<Class<?>> exclusionPredicate)`.
+
 ## [3.18.2] - 2025-01-30
 
 ### Fixed

docs/_manual/08-several-classes-at-once.md

@@ -16,11 +16,14 @@ This will test each class within the `com.example.app.domain` package.
 If there's a class within that package that you don't want to test with EqualsVerifier, for instance a helper class, you can exclude it as follows:
 
 {% highlight java %}
-EqualsVerifier.forPackage("com.example.app.domain")
-    .except(Helper.class)
+EqualsVerifier.forPackage(
+        "com.example.app.domain",
+        ScanOption.except(Helper.class))
     .verify();
 {% endhighlight %}
 
+Note that the `ScanOption` class contains several more tools to fine-tune your search. `ScanOption.recursive()` will let EqualsVerifier look in all the sub-packages of `com.example.app.domain` and `ScanOption.mustExtend(Foo.class)` only finds classes that extend or implement `Foo.class`.
+
 You can achieve even more granularity:
 
 {% highlight java %}