[MNG-8029] improve documentation about mirror settings

apache · Feb 17, 2024 · 13a0426 · 13a0426
1 parent 13a1f5d
commit 13a0426
Show file tree

Hide file tree

Showing 18 changed files with 54 additions and 77 deletions.
diff --git a/apache-maven/src/site/site.xml b/apache-maven/src/site/site.xml
@@ -23,9 +23,4 @@ under the License.
   xsi:schemaLocation="http://maven.apache.org/DECORATION/1.8.0 http://maven.apache.org/xsd/decoration-1.8.0.xsd">
 
   <edit>${project.scm.url}</edit>
-
-  <body>
-    <menu ref="parent"/>
-    <menu ref="reports"/>
-  </body>
 </project>
diff --git a/maven-artifact/src/site/site.xml b/maven-artifact/src/site/site.xml
@@ -31,8 +31,5 @@ under the License.
       <item name="Source Xref" href="xref/index.html"/>
       <!--item name="FAQ" href="faq.html"/-->
     </menu>
-
-    <menu ref="parent"/>
-    <menu ref="reports"/>
   </body>
 </project>
diff --git a/maven-builder-support/src/site/site.xml b/maven-builder-support/src/site/site.xml
@@ -31,8 +31,5 @@ under the License.
       <item name="Source Xref" href="xref/index.html"/>
       <!--item name="FAQ" href="faq.html"/-->
     </menu>
-
-    <menu ref="parent"/>
-    <menu ref="reports"/>
   </body>
 </project>
diff --git a/maven-compat/src/site/site.xml b/maven-compat/src/site/site.xml
@@ -31,8 +31,5 @@ under the License.
       <item name="Source Xref" href="xref/index.html"/>
       <!--item name="FAQ" href="faq.html"/-->
     </menu>
-
-    <menu ref="parent"/>
-    <menu ref="reports"/>
   </body>
 </project>
diff --git a/maven-core/src/main/java/org/apache/maven/bridge/MavenRepositorySystem.java b/maven-core/src/main/java/org/apache/maven/bridge/MavenRepositorySystem.java
@@ -63,6 +63,7 @@
 
 /**
  * @author Jason van Zyl
+ * @since 3.2.3
  */
 @Component(role = MavenRepositorySystem.class, hint = "default")
 public class MavenRepositorySystem {
@@ -677,15 +678,15 @@ public static Mirror getMirror(ArtifactRepository repository, List<Mirror> mirro
     /**
      * This method checks if the pattern matches the originalRepository. Valid patterns:
      * <ul>
-     * <li>{@code *} = everything,</li>
-     * <li>{@code external:*} = everything not on the localhost and not file based,</li>
-     * <li>{@code external:http:*} = any repository not on the localhost using HTTP,</li>
-     * <li>{@code repo,repo1} = {@code repo} or {@code repo1},</li>
-     * <li>{@code *,!repo1} = everything except {@code repo1}.</li>
+     * <li>{@code *} (since 2.0.5)= everything,</li>
+     * <li>{@code external:*}  (since 2.0.9)= everything not on the localhost and not file based,</li>
+     * <li>{@code external:http:*} (since 3.8.0)= any repository not on the localhost using HTTP,</li>
+     * <li>{@code repo,repo1}  (since 2.0.9)= {@code repo} or {@code repo1},</li>
+     * <li>{@code *,!repo1} (since 2.0.9)= everything except {@code repo1}.</li>
      * </ul>
      *
      * @param originalRepository to compare for a match.
-     * @param pattern used for match. Currently only '*' is supported.
+     * @param pattern used for match.
      * @return true if the repository is a match to this pattern.
      */
     static boolean matchPattern(ArtifactRepository originalRepository, String pattern) {

diff --git a/maven-core/src/site/site.xml b/maven-core/src/site/site.xml
@@ -33,13 +33,7 @@ under the License.
     </menu>
 
     <menu name="Reference">
-      <item name="Lifecycles" href="lifecycles.html"/>
-      <item name="Plugin Bindings to Default Lifecycle" href="default-bindings.html"/>
-      <item name="Artifact Handlers" href="artifact-handlers.html"/>
       <item name="Core Extensions" href="core-extensions.html"/>
     </menu>
-
-    <menu ref="parent"/>
-    <menu ref="reports"/>
   </body>
 </project>
diff --git a/maven-embedder/src/site/site.xml b/maven-embedder/src/site/site.xml
@@ -31,12 +31,5 @@ under the License.
       <item name="Source Xref" href="xref/index.html"/>
       <!--item name="FAQ" href="faq.html"/-->
     </menu>
-
-    <menu name="Reference">
-      <item name="CLI options" href="cli.html"/>
-    </menu>
-
-    <menu ref="parent"/>
-    <menu ref="reports"/>
   </body>
 </project>
diff --git a/maven-model-builder/src/site/site.xml b/maven-model-builder/src/site/site.xml
@@ -31,12 +31,5 @@ under the License.
       <item name="Source Xref" href="xref/index.html"/>
       <!--item name="FAQ" href="faq.html"/-->
     </menu>
-
-    <menu name="Reference">
-      <item name="Super POM" href="super-pom.html"/>
-    </menu>
-
-    <menu ref="parent"/>
-    <menu ref="reports"/>
   </body>
 </project>
diff --git a/maven-model/src/site/site.xml b/maven-model/src/site/site.xml
@@ -31,8 +31,5 @@ under the License.
       <item name="Source Xref" href="xref/index.html"/>
       <!--item name="FAQ" href="faq.html"/-->
     </menu>
-
-    <menu ref="parent"/>
-    <menu ref="reports"/>
   </body>
 </project>
diff --git a/maven-plugin-api/src/site/site.xml b/maven-plugin-api/src/site/site.xml
@@ -35,8 +35,5 @@
       <item name="META-INF/maven/lifecycle.xml" href="lifecycle-mappings.html"/>
       <item name="META-INF/maven/plugin.xml" href="plugin.html"/>
     </menu>
-
-    <menu ref="parent"/>
-    <menu ref="reports"/>
   </body>
 </project>
diff --git a/maven-repository-metadata/src/site/site.xml b/maven-repository-metadata/src/site/site.xml
@@ -31,8 +31,5 @@ under the License.
       <!--item name="Source Xref" href="xref/index.html"/-->
       <!--item name="FAQ" href="faq.html"/-->
     </menu>
-
-    <menu ref="parent"/>
-    <menu ref="reports"/>
   </body>
 </project>
diff --git a/maven-resolver-provider/src/site/site.xml b/maven-resolver-provider/src/site/site.xml
@@ -31,8 +31,5 @@ under the License.
       <item name="Source Xref" href="xref/index.html"/>
       <!--item name="FAQ" href="faq.html"/-->
     </menu>
-
-    <menu ref="parent"/>
-    <menu ref="reports"/>
   </body>
 </project>
diff --git a/maven-settings-builder/src/site/site.xml b/maven-settings-builder/src/site/site.xml
@@ -31,8 +31,5 @@ under the License.
       <item name="Source Xref" href="xref/index.html"/>
       <!--item name="FAQ" href="faq.html"/-->
     </menu>
-
-    <menu ref="parent"/>
-    <menu ref="reports"/>
   </body>
 </project>
diff --git a/maven-settings/src/main/mdo/settings.mdo b/maven-settings/src/main/mdo/settings.mdo
@@ -28,9 +28,9 @@
   <description>
     <![CDATA[
     <p>This is a reference for the user-specific configuration for Maven.</p>
-    <p>Includes things that should not be distributed with the pom.xml file, such as developer identity, along with
+    <p>Includes things that should not be distributed with the <code>pom.xml</code> file, such as developer identity, along with
     local settings, like proxy information.</p>
-    <p>The default location for the settings file is <i>~/.m2/settings.xml</i></p>
+    <p>The default location for the user settings file is <code>~/.m2/settings.xml</code></p>
     ]]>
   </description>
   <defaults>
@@ -99,6 +99,7 @@
           <type>String</type>
           <defaultValue>default</defaultValue>
           <required>true</required>
+          <description>Item identifier.</description>
         </field>
       </fields>
     </class>
@@ -137,7 +138,7 @@
           <version>1.0.0+</version>
           <description>
             <![CDATA[
-            Whether Maven should use the plugin-registry.xml file to manage plugin versions.
+            Whether Maven should use the <code>plugin-registry.xml</code> file to manage plugin versions.
             ]]>
           </description>
           <type>boolean</type>
@@ -169,8 +170,8 @@
           <version>1.0.0+</version>
           <description><![CDATA[
           Configuration for different java environment profiles. One good use
-          for this might be to configure both JDK 1.4 and JDK 1.5 to work with
-          maven. Profiles will allow switching of entire java environments
+          for this might be to configure both JDK 1.4 and JDK 5 to work with
+          Maven. Profiles will allow switching of entire java environments
           based on the profile id, either in the defaults section below, or on
           the command line.
           ]]></description>
@@ -495,7 +496,7 @@
           <version>1.0.0+</version>
           <description>
             <![CDATA[
-            The list of non-proxied hosts (delimited by |).
+            The list of non-proxied hosts (delimited by <code>|</code>).
             ]]>
           </description>
           <type>String</type>
@@ -596,8 +597,12 @@
           <version>1.0.0+</version>
           <type>String</type>
           <description>
-            The server ID of the repository being mirrored, e.g.,
-            "central". This MUST NOT match the mirror id.
+            <![CDATA[
+            A repository id or (since Maven 2.0.9) an expression matching one or many repository ids to mirror, e.g.,
+            <code>central</code> or <code>*,!repo1</code>.
+            <code>*</code> (since Maven 2.0.5), <code>external:*</code> (since Maven 2.0.9) and <code>external:http:*</code> (since Maven 3.8.0) have
+            a special meaning: see <a href="/guides/mini/guide-mirror-settings.html">Mirror Settings</a> guide.
+            ]]>
           </description>
         </field>
         <field>
@@ -621,16 +626,24 @@
           <version>1.1.0+</version>
           <type>String</type>
           <defaultValue>default</defaultValue>
-          <description>The layout of the mirror repository. Since Maven 3.</description>
+          <description>
+            <![CDATA[
+            The layout of the mirror repository.
+            <br><b>Since</b>: Maven 3
+            ]]>
+          </description>
         </field>
         <field>
           <name>mirrorOfLayouts</name>
           <version>1.1.0+</version>
           <type>String</type>
           <defaultValue>default,legacy</defaultValue>
           <description>
+            <![CDATA[
             The layouts of repositories being mirrored. This value can be used to restrict the usage
-            of the mirror to repositories with a matching layout (apart from a matching id). Since Maven 3.
+            of the mirror to repositories with a matching layout (apart from a matching id).
+            <br><b>Since</b>: Maven 3
+            ]]>
           </description>
         </field>
         <field>
@@ -639,7 +652,11 @@
           <type>boolean</type>
           <defaultValue>false</defaultValue>
           <description>
+            <![CDATA[
             Whether this mirror should be blocked from any download request but fail the download process, explaining why.
+            <br><b>Default value is</b>: <code>false</code>
+            <br><b>Since</b>: Maven 3.8.0
+            ]]>
           </description>
         </field>
       </fields>

diff --git a/maven-settings/src/site/apt/index.apt b/maven-settings/src/site/apt/index.apt
@@ -25,7 +25,8 @@
 
 Maven Settings Model
 
- This is strictly the model for Maven settings.
+ This is strictly the model for Maven settings. All the effective settings building logic from multiple <<<settings.xml>>> files
+ is done in {{{../maven-settings-builder/}Maven Settings Builder}}.
 
  The following are generated from this model:
 
@@ -34,3 +35,15 @@ Maven Settings Model
    * A {{{./settings.html}Descriptor Reference}}
 
    * An {{{https://maven.apache.org/xsd/settings-1.2.0.xsd}XSD}}
+
+* See Also User Documentation
+
+  * {{{https://maven.apache.org/settings.html} Settings Reference}},
+
+  * {{{https://maven.apache.org/guides/mini/guide-mirror-settings.html} Mirror Settings}},
+
+  * {{{https://maven.apache.org/guides/mini/guide-deployment-security-settings.html} Security and Deployment Settings}},
+
+  * {{{https://maven.apache.org/guides/mini/guide-encryption.html} Password Encryption}},
+
+  * {{{https://maven.apache.org/guides/mini/guide-proxies.html} Configuring a proxy}}.
diff --git a/maven-settings/src/site/site.xml b/maven-settings/src/site/site.xml
@@ -31,8 +31,5 @@ under the License.
       <item name="Source Xref" href="xref/index.html"/>
       <!--item name="FAQ" href="faq.html"/-->
     </menu>
-
-    <menu ref="parent"/>
-    <menu ref="reports"/>
   </body>
 </project>
diff --git a/maven-slf4j-provider/src/site/site.xml b/maven-slf4j-provider/src/site/site.xml
@@ -31,8 +31,5 @@ under the License.
       <item name="Source Xref" href="xref/index.html"/>
       <!--item name="FAQ" href="faq.html"/-->
     </menu>
-
-    <menu ref="parent"/>
-    <menu ref="reports"/>
   </body>
 </project>
diff --git a/src/site/site.xml b/src/site/site.xml
@@ -46,25 +46,26 @@ under the License.
       <item name="Download" href="/download.html"/>
     </menu>
 
-    <menu name="Descriptors Reference">
+    <menu inherit="bottom" name="Descriptors Reference">
       <item name="POM" href="./maven-model/maven.html"/>
       <item name="Settings" href="./maven-settings/settings.html"/>
       <item name="Toolchains" href="./maven-core/toolchains.html"/>
     </menu>
 
-    <menu name="Reference">
+    <menu inherit="bottom" name="Reference">
       <item name="Lifecycles" href="./maven-core/lifecycles.html"/>
       <item name="Plugin Bindings to Default Lifecycle" href="./maven-core/default-bindings.html"/>
       <item name="Artifact Handlers" href="./maven-core/artifact-handlers.html"/>
       <item name="CLI options" href="./maven-embedder/cli.html"/>
+      <item name="Super POM" href="./maven-model-builder/super-pom.html"/>
     </menu>
 
-    <menu name="Development">
+    <menu inherit="bottom" name="Development">
       <item name="Maven Developer Centre" href="../../developers/index.html"/>
       <item name="Maven Core ITs" href="../../core-its/index.html"/>
     </menu>
 
-    <menu ref="modules"/>
-    <menu ref="reports"/>
+    <menu inherit="bottom" ref="modules"/>
+    <menu inherit="bottom" ref="reports"/>
   </body>
 </project>