diff --git a/api/maven-api-model/src/main/mdo/maven.mdo b/api/maven-api-model/src/main/mdo/maven.mdo
index 2829ffdc225b..4a9c05f77e30 100644
--- a/api/maven-api-model/src/main/mdo/maven.mdo
+++ b/api/maven-api-model/src/main/mdo/maven.mdo
@@ -775,6 +775,7 @@
String
+
resources3.0.0+
@@ -789,6 +790,7 @@
+
testResources4.0.0+
@@ -857,6 +859,22 @@
+ sources
+ 4.1.0+
+
+ All the sources to compile and resources files to copy for a project or it's unit tests.
+ The sources can be Java source files, generated source files, scripts or resources for examples.
+ Each source is specified by a mandatory {@code directory} element, which is relative to the POM.
+ The kind of sources (codes to compile or resources to copy) and their usage (for the main code
+ or for the tests) is specified by the {@code scope} element together with each source directory.
+
+
+ Source
+ *
+
+
+
+
sourceDirectory3.0.0+true
@@ -869,6 +887,7 @@
String
+
scriptSourceDirectory4.0.0+true
@@ -882,6 +901,7 @@
String
+
testSourceDirectory4.0.0+true
@@ -1945,6 +1965,178 @@
+ Source
+
+ etc.) and their
+ usage (main code, tests, etc.) is specified by the {@code scope} element.
+
+
Default source directories
+ If no source directories are specified, the defaults are {@code src/${scope}/${lang}} where
+ {@code ${scope}} is the value of the {@link #scope} element (typically {@code main} or {@code test}) and
+ {@code ${lang}} is the value of the {@link #lang} element (typically {@code java} or {@code resources}).
+ ]]>
+
+ 4.1.0+
+ FileSet
+
+
+ scope
+ 4.1.0+
+
+ The main scope is used for specifying a directory containing the source of the project.
+ The generated build system will compile the sources from this directory when the project is built.
+ The path given in the {@code directory} field is relative to the project descriptor.
+ The default directory for the default language (Java) is {@code "src/main/java"}.
+
+
The test scope is used for specifying a directory containing the unit test source of the project.
+ The generated build system will compile these directories when the project is being tested.
+ The path given in the {@code directory} field is relative to the project descriptor.
+ The default directory for the default language (Java) is {@code "src/test/java"}.
+
+
If no scope is specified, the default is {@code main}.
+ ]]>
+
+ String
+ main
+
+
+ lang
+ 4.1.0+
+
+ JSON or XML).
+
+
The java language is used for specifying a directory containing the Java sources of the project.
+ The generated build system will compile the sources from this directory using the Java compiler when the
+ project is built. The path given in the {@code directory} field is relative to the project descriptor.
+ The default directory for the main Java sources is {@code "src/main/java"}.
+
+
The resources language is used for specifying a directory containing the class-path
+ or module-path resources such as properties files or scripts associated with a project.
+ This directory is meant to be different from the main source directory,
+ in that its contents will be copied to the output directory in most cases
+ (since scripts are interpreted rather than compiled).
+ The default directory for the main resources is {@code "src/main/resources"}.
+
+
If no language is specified, the default is {@code java}.
+ ]]>
+
+ String
+ main
+
+
+ module
+ 4.1.0+
+
+ If a module name is specified for resources or script files,
+ then this value modifies the directory where the files will be copied.
+ For example, if a Java module name is "foo.biz", then the {@code foo/bar.properties}
+ resource file will be copied as {@code foo.biz/foo/bar.properties}.
+
+
This element can be combined with the {@code targetVersion} element for specifying sources,
+ scripts or resources that are specific to both a particular module and a target version.
+ ]]>
+
+ String
+
+
+ targetVersion
+ 4.1.0+
+
+ JAR file will be created.
+ If this element is omitted, then the default target version is the compiler default value,
+ which is usually the version of the Java environment running Maven.
+
+
If a target version is specified for resources or script files,
+ then this value modifies the directory where the files will be copied.
+ For example, if {@code targetVersion} is 17, then the {@code foo/bar.properties}
+ resource file will be copied as {@code META-INF/versions/17/foo/bar.properties}.
+
+
This element can be combined with the {@code module} element for specifying sources,
+ scripts or resources that are specific to both a particular module and a target version.
+ ]]>
+
+ String
+
+
+ targetPath
+ 4.1.0+
+
+ When a target path is explicitly specified, the values of the {@code module} and {@code targetVersion}
+ elements are not used for inferring the path (they are still used as compiler options however).
+ It means that for scripts and resources, the files below the path specified by {@code directory}
+ are copied to the path specified by {@code targetPath} with the exact same directory structure.
+ It is user's responsibility to put module and version components in the {@code targetPath} if needed.
+
+
Note that for Java source files, a directory with the module name may still be generated despite
+ above statement about {@code module} being ignored, because that directory is generated by the Java
+ compiler rather than Maven.
+ ]]>
+
+ String
+
+
+ filtering
+ 4.1.0+
+
+ This filtering should not be confused with the filtering of paths done by the
+ {@code includes} and {@code excludes} patterns.
+
+