diff --git a/src/main/java/org/apache/maven/plugin/compiler/AbstractCompilerMojo.java b/src/main/java/org/apache/maven/plugin/compiler/AbstractCompilerMojo.java
index 08eeeb269..57b3c61ee 100644
--- a/src/main/java/org/apache/maven/plugin/compiler/AbstractCompilerMojo.java
+++ b/src/main/java/org/apache/maven/plugin/compiler/AbstractCompilerMojo.java
@@ -432,21 +432,28 @@ final Charset charset() {
      *
      * @see #debuglevel
      * @see <a href="https://docs.oracle.com/en/java/javase/17/docs/specs/man/javac.html#option-g">javac -g</a>
+     *
+     * @deprecated Setting this flag to {@code false} is replaced by {@code <debuglevel>none</debuglevel>}.
      */
+    @Deprecated(since = "4.0.0")
     @Parameter(property = "maven.compiler.debug", defaultValue = "true")
     protected boolean debug = true;
 
     /**
-     * Keyword list to be appended to the {@code -g} command-line switch.
-     * Legal values are a comma-separated list of the following keywords:
-     * {@code lines}, {@code vars}, {@code source} and {@code all}.
-     * If debug level is not specified, then the {@code -g} option will <em>not</em> by added,
+     * Kinds of debugging information to include in the compiled class files.
+     * Legal values are {@code lines}, {@code vars}, {@code source}, {@code all} and {@code none}.
+     * Values other than {@code all} and {@code none} can be combined in a comma-separated list.
+     *
+     * <p>If debug level is not specified, then the {@code -g} option will <em>not</em> be added,
      * which means that the default debugging information will be generated
-     * (typically {@code lines} and {@code source} but not {@code vars}).
-     * If {@link #debug} is turned off, this attribute will be ignored.
+     * (typically {@code lines} and {@code source} but not {@code vars}).</p>
+     *
+     * <p>If debug level is {@code all}, then only the {@code -g} option is added,
+     * which means that all debugging information will be generated.
+     * If debug level is anything else, then the comma-separated list of keywords
+     * is appended to the {@code -g} command-line switch.</p>
      *
-     * @see #debug
-     * @see <a href="https://docs.oracle.com/en/java/javase/17/docs/specs/man/javac.html#option-g-custom">javac -G:[lines,vars,source]</a>
+     * @see <a href="https://docs.oracle.com/en/java/javase/17/docs/specs/man/javac.html#option-g-custom">javac -g:[lines,vars,source]</a>
      * @since 2.1
      */
     @Parameter(property = "maven.compiler.debuglevel")