desruisseaux commented on code in PR #1936:
URL: https://github.com/apache/maven/pull/1936#discussion_r1857065914
##########
api/maven-api-model/src/main/mdo/maven.mdo:
##########
@@ -1945,6 +1965,178 @@
</codeSegments>
</class>
<class>
+ <name>Source</name>
+ <description>
+ <![CDATA[
+ Description of the sources associated with a project main code or unit
tests.
+ The sources can be Java source files, generated source files, scripts
or resources for examples.
+ A source is specified by a mandatory {@code directory} element, which
is relative to the POM.
+ The directory content can optionally by reduced to a subset with the
{@code includes} and
+ {@code excludes} elements. The kind of sources (codes, resources,
<i>etc.</i>) and their
+ usage (main code, tests, <i>etc.</i>) is specified by the {@code
scope} element.
+
+ <h2>Default source directories</h2>
+ 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}).
+ ]]>
+ </description>
+ <version>4.1.0+</version>
+ <superClass>FileSet</superClass>
+ <fields>
+ <field>
+ <name>scope</name>
+ <version>4.1.0+</version>
+ <description>
+ <![CDATA[
+ Specifies in which context the source files will be used -
typically {@code main} or {@code test}.
+
+ <p>The <b>main</b> 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"}.</p>
+
+ <p>The <b>test</b> 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"}.</p>
+
+ <p>If no scope is specified, the default is {@code main}.</p>
+ ]]>
+ </description>
+ <type>String</type>
+ <defaultValue>main</defaultValue>
+ </field>
+ <field>
+ <name>lang</name>
+ <version>4.1.0+</version>
+ <description>
+ <![CDATA[
+ Specifies the language of the source files - typically {@code
java} or {@code resources}.
+ Resources is used as a generic term for scripting languages (e.g.,
JavaScript or Python)
+ or markup languages (e.g. properties file, <abbr>JSON</abbr> or
<abbr>XML</abbr>).
+
+ <p>The <b>java</b> 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"}.</p>
+
+ <p>The <b>resources</b> 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"}.</p>
+
+ <p>If no language is specified, the default is {@code java}.</p>
+ ]]>
+ </description>
+ <type>String</type>
+ <defaultValue>main</defaultValue>
+ </field>
+ <field>
+ <name>module</name>
+ <version>4.1.0+</version>
+ <description>
+ <![CDATA[
+ Name of the Java module (or other language-specific module) which
is built by the sources.
+ This element can be specified in a Maven project containing
multiple Java modules.
+ It is generally not needed for non-modular projects, or for
modular projects having only one module.
+
+ <p>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}.</p>
+
+ <p>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.</p>
+ ]]>
+ </description>
+ <type>String</type>
+ </field>
+ <field>
+ <name>targetVersion</name>
+ <version>4.1.0+</version>
+ <description>
+ <![CDATA[
+ The version of the platform where the code will be executed.
+ In a Java environment, this is the value of the {@code --release}
compiler option.
+ If a Java project contains multiple main sources with different
target versions,
+ then a multi-version <abbr>JAR</abbr> 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.
+
+ <p>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}.</p>
+
+ <p>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.</p>
+ ]]>
+ </description>
+ <type>String</type>
+ </field>
+ <field>
+ <name>targetPath</name>
+ <version>4.1.0+</version>
+ <description>
+ <![CDATA[
+ Specifies an explicit target path, overriding the default value.
+ The path is relative to the {@code
${project.build.outputDirectory}} directory,
+ which is typically {@code target/classes} in a Java project.
+
+ <p>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.</p>
+
+ <p>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.</p>
+ ]]>
+ </description>
+ <type>String</type>
+ </field>
+ <field>
+ <name>filtering</name>
+ <version>4.1.0+</version>
+ <description>
+ <![CDATA[
+ Whether resources are filtered to replace tokens with
parameterized values.
+ The values are taken from the {@code properties} element and from
the properties
+ in the files listed in the {@code filters} element.
+
+ <p>This filtering should not be confused with the filtering of
paths done by the
+ {@code includes} and {@code excludes} patterns.</p>
+
+ <p>The default value is {@code false}.</p>
+ ]]>
+ </description>
+ <type>boolean</type>
+ <defaultValue>false</defaultValue>
+ </field>
+ <field>
+ <name>enabled</name>
+ <version>4.1.0+</version>
+ <description>
+ <