Clarify minimize and R8 behavior

[Goooler]

Refs #2123.

[Copilot]

Pull request overview

This PR improves the clarity and user-facing documentation around Shadow’s dependency-analysis minimization (minimize()) and R8 post-processing (r8()), including how they relate, their execution order, and the corresponding CLI options.

Changes:

• Clarify KDoc and CLI option descriptions for minimize-jar and enable-r8 to emphasize that minimization and R8 are independent features with a defined execution order when both are enabled.
• Update user documentation (MkDocs nav + minimizing docs + getting started) to explain the two mechanisms side-by-side and document the deprecated nested minimize { r8 { ... } } compatibility DSL behavior.
• Add a functional test ensuring --no-enable-r8 overrides an r8 {} block in build configuration.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/main/kotlin/com/github/jengelman/gradle/plugins/shadow/tasks/ShadowJar.kt	Updates KDoc and CLI option descriptions for minimization and R8 behavior/order.
src/main/kotlin/com/github/jengelman/gradle/plugins/shadow/tasks/R8Spec.kt	Expands KDoc to clarify R8 rules are independent of minimize() exclusions.
src/functionalTest/kotlin/com/github/jengelman/gradle/plugins/shadow/MinimizeTest.kt	Adds coverage ensuring CLI disabling of R8 overrides an r8 {} block.
src/functionalTest/kotlin/com/github/jengelman/gradle/plugins/shadow/JavaPluginsTest.kt	Updates expected shadowJar help output strings for CLI options.
mkdocs.yml	Renames nav entry to reflect combined “Minimizing and R8” documentation.
docs/getting-started/README.md	Updates documented CLI option descriptions for minimization and R8.
docs/configuration/minimizing/README.md	Reframes page to explain minimization vs R8 and documents deprecated nested R8 configuration behavior.

Comments suppressed due to low confidence (1)

src/main/kotlin/com/github/jengelman/gradle/plugins/shadow/tasks/ShadowJar.kt:410

• The minimize(...) KDoc says it "does not enable R8", but minimize { r8 { ... } } is still supported via the deprecated MinimizeSpec.r8(...) compatibility DSL, and that path does enable R8 (via legacyR8Enabled). Please qualify this statement so the docs stay accurate until the compatibility layer is removed.

   * This removes unused classes from selected dependency JARs while assembling the shadowed JAR. It
   * does not enable R8. If [r8] is also configured, R8 post-processing runs afterward.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.