[MNG-5987] document goals execution order

fixes #1145

maven-core/src/site/apt/index.apt

@@ -49,7 +49,24 @@ Maven Core
 
  * <<<ProjectBuilder>>> component ({{{./apidocs/org/apache/maven/project/ProjectBuilder.html}javadoc}}),
  with its <<<DefaultProjectBuilder>>> implementation
- ({{{./xref/org/apache/maven/project/DefaultProjectBuilder.html}source}}),
+ ({{{./xref/org/apache/maven/project/DefaultProjectBuilder.html}source}}), to prepare {{{./apidocs/org/apache/maven/project/MavenProject.html}<<<MavenProject>>> descriptor}} from POM files,
+
+ * <<<LifecycleExecutor>>> component ({{{./apidocs/org/apache/maven/lifecycle/LifecycleExecutor.html}javadoc}}),
+ with its <<<DefaultLifecycleExecutor>>> implementation({{{/xref/org/apache/maven/lifecycle/DefaultLifecycleExecutor.html}source}}), to plan or execute tasks.\
+   on plugin goals execution order:
+
+   * <<in a given phase, goals order is not expected to be guaranteed nor finely tuned>>:
+     it is just a consequence of the order obtained during {{{../maven-model-builder/}effective model building}},
+     which combines profile activation+injection and inheritance assembly from parents,
+
+   * known limitations are notably that:
+
+     1. plugin goal execution in a child is usually simply appended (at end): you can't try to insert in the middle of pre-existing inherited executions,
+
+     2. append happens at plugin level first, then goal level, independently from phases.
+        This means for example that adding pluginA:goal2 to pre-existing (pluginA:goal1, pluginB:goal) will lead to (pluginA:goal1, pluginA:goal2, pluginB:goal)
+
+   * see effective POM as shown by {{{/plugins/maven-help-plugin/effective-pom-mojo.html}<<<help:effective-pom>>>}} to see the effective plugins then goals order.
 
  * <<<MavenPluginManager>>> component ({{{./apidocs/org/apache/maven/plugin/MavenPluginManager.html}javadoc}}),
  with its <<<DefaultMavenPluginManager>>> implementation

maven-plugin-api/src/main/mdo/plugin.mdo

@@ -25,8 +25,9 @@ under the License.
     Plugin descriptor, stored in <code>META-INF/maven/plugin.xml</code> in a plugin's jar artifact.
     This descriptor is generally generated from plugin sources, using
     <a href="/plugins/maven-plugin-plugin/">maven-plugin-plugin</a>.
-    <p><i>Notice:</i> this documentation is generated from a Modello model but the code executed is not generated
-    from this descriptor. Please report if you find anything wrong.</p>
+    <p><i>Notice:</i> this documentation is generated from a Modello model but the
+    <a href="apidocs/org/apache/maven/plugin/descriptor/PluginDescriptor.html"><code>PluginDescriptor</code></a>/<a href="apidocs/org/apache/maven/plugin/descriptor/MojoDescriptor.html"><code>MojoDescriptor</code></a>
+    code executed is not generated from this model. Please report if you find anything wrong this documentation.</p>
   ]]></description>
   <defaults>
     <default>

maven-plugin-api/src/site/apt/index.apt

@@ -25,7 +25,13 @@
 
 Maven Plugin API
 
- The API for plugins - composed of goals implemented by Mojos - development.
+ The API for plugins - composed of goals implemented by Mojos - development:
+
+ * goal code extends {{{./apidocs/org/apache/maven/plugin/AbstractMojo.html}<<<AbstractMojo>>> base class}} that implements {{{./apidocs/org/apache/maven/plugin/Mojo.html}<<<Mojo>>> interface}},
+
+ * {{{./apidocs/org/apache/maven/plugin/logging/Log.html}<<<Log>>> interface}} provides easy logging for the goal.
+
+ []
 
  A plugin is described in a {{{./plugin.html}<<<META-INF/maven/plugin.xml>>> plugin descriptor}},
  generally generated from plugin sources using {{{/plugin-tools/maven-plugin-plugin/}maven-plugin-plugin}}.
@@ -34,6 +40,6 @@ Maven Plugin API
 
  * {{{/developers/mojo-api-specification.html}Mojo API Specification}}
 
- * {{{/plugin-tools/}plugin-tools}}
+ * {{{/plugin-tools/}Plugin Tools}} that provide {{{/plugin-tools/maven-plugin-plugin/}maven-plugin-plugin}} to generate the {{{./plugin.html}<<<META-INF/maven/plugin.xml>>> plugin descriptor}}
 
- * {{{/plugin-testing/}plugin-testing}}
+ * {{{/plugin-testing/}Plugin Testing}} frameworks

maven-plugin-api/src/site/site.xml

@@ -32,8 +32,8 @@
       <!--item name="FAQ" href="faq.html"/-->
     </menu>
     <menu name="Reference">
-      <item name="lifecycle.xml" href="lifecycle-mappings.html"/>
-      <item name="plugin.xml" href="plugin.html"/>
+      <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"/>