maven-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From schu...@apache.org
Subject [21/29] maven git commit: improved documentation
Date Wed, 25 Jan 2017 21:17:44 GMT
improved documentation

Project: http://git-wip-us.apache.org/repos/asf/maven/repo
Commit: http://git-wip-us.apache.org/repos/asf/maven/commit/512fa6a4
Tree: http://git-wip-us.apache.org/repos/asf/maven/tree/512fa6a4
Diff: http://git-wip-us.apache.org/repos/asf/maven/diff/512fa6a4

Branch: refs/heads/MNG-2199
Commit: 512fa6a45b73663ed5b5e0e896539d1084da36f3
Parents: 0b684af
Author: Hervé Boutemy <hboutemy@apache.org>
Authored: Sun Oct 2 10:02:21 2016 +0200
Committer: Hervé Boutemy <hboutemy@apache.org>
Committed: Wed Jan 25 00:07:55 2017 +0100

----------------------------------------------------------------------
 maven-core/project-builder.txt                  |   1 -
 .../src/main/java/org/apache/maven/Maven.java   |   3 +
 .../java/org/apache/maven/SessionScoped.java    |   4 +-
 .../apache/maven/execution/MavenSession.java    |   2 +
 .../maven/execution/ProjectDependencyGraph.java |   1 +
 .../org/apache/maven/graph/GraphBuilder.java    |   5 +
 maven-core/src/site/apt/index.apt               |  23 ++-
 .../apt/scripting-support/marmalade-support.apt | 196 -------------------
 8 files changed, 26 insertions(+), 209 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/maven/blob/512fa6a4/maven-core/project-builder.txt
----------------------------------------------------------------------
diff --git a/maven-core/project-builder.txt b/maven-core/project-builder.txt
deleted file mode 100644
index a9aab65..0000000
--- a/maven-core/project-builder.txt
+++ /dev/null
@@ -1 +0,0 @@
-Maven Project Builder and Maven Model Builder

http://git-wip-us.apache.org/repos/asf/maven/blob/512fa6a4/maven-core/src/main/java/org/apache/maven/Maven.java
----------------------------------------------------------------------
diff --git a/maven-core/src/main/java/org/apache/maven/Maven.java b/maven-core/src/main/java/org/apache/maven/Maven.java
index 8563847..69f9fca 100644
--- a/maven-core/src/main/java/org/apache/maven/Maven.java
+++ b/maven-core/src/main/java/org/apache/maven/Maven.java
@@ -23,7 +23,10 @@ import org.apache.maven.execution.MavenExecutionRequest;
 import org.apache.maven.execution.MavenExecutionResult;
 
 /**
+ * The main Maven execution entry point, which will execute a full Maven execution session.
+ *
  * @author Jason van Zyl
+ * @see org.apache.maven.execution.MavenSession
  */
 public interface Maven
 {

http://git-wip-us.apache.org/repos/asf/maven/blob/512fa6a4/maven-core/src/main/java/org/apache/maven/SessionScoped.java
----------------------------------------------------------------------
diff --git a/maven-core/src/main/java/org/apache/maven/SessionScoped.java b/maven-core/src/main/java/org/apache/maven/SessionScoped.java
index 63b1eb7..7738938 100644
--- a/maven-core/src/main/java/org/apache/maven/SessionScoped.java
+++ b/maven-core/src/main/java/org/apache/maven/SessionScoped.java
@@ -28,8 +28,8 @@ import java.lang.annotation.Target;
 import com.google.inject.ScopeAnnotation;
 
 /**
- * Indicates that annotated component should be instantiated before session starts and discarded
after session execution
- * completes.
+ * Indicates that annotated component should be instantiated before session execution starts
+ * and discarded after session execution completes.
  *
  * @author Jason van Zyl
  * @since 3.2.0

http://git-wip-us.apache.org/repos/asf/maven/blob/512fa6a4/maven-core/src/main/java/org/apache/maven/execution/MavenSession.java
----------------------------------------------------------------------
diff --git a/maven-core/src/main/java/org/apache/maven/execution/MavenSession.java b/maven-core/src/main/java/org/apache/maven/execution/MavenSession.java
index 864c49ad..d69bbba 100644
--- a/maven-core/src/main/java/org/apache/maven/execution/MavenSession.java
+++ b/maven-core/src/main/java/org/apache/maven/execution/MavenSession.java
@@ -39,6 +39,8 @@ import org.codehaus.plexus.component.repository.exception.ComponentLookupExcepti
 import org.eclipse.aether.RepositorySystemSession;
 
 /**
+ * A Maven execution session.
+ *
  * @author Jason van Zyl
  */
 public class MavenSession

http://git-wip-us.apache.org/repos/asf/maven/blob/512fa6a4/maven-core/src/main/java/org/apache/maven/execution/ProjectDependencyGraph.java
----------------------------------------------------------------------
diff --git a/maven-core/src/main/java/org/apache/maven/execution/ProjectDependencyGraph.java
b/maven-core/src/main/java/org/apache/maven/execution/ProjectDependencyGraph.java
index 1db277d..0d5584b 100644
--- a/maven-core/src/main/java/org/apache/maven/execution/ProjectDependencyGraph.java
+++ b/maven-core/src/main/java/org/apache/maven/execution/ProjectDependencyGraph.java
@@ -27,6 +27,7 @@ import org.apache.maven.project.MavenProject;
  * Describes the inter-dependencies between projects in the reactor.
  *
  * @author Benjamin Bentmann
+ * @since 3.0-alpha
  */
 public interface ProjectDependencyGraph
 {

http://git-wip-us.apache.org/repos/asf/maven/blob/512fa6a4/maven-core/src/main/java/org/apache/maven/graph/GraphBuilder.java
----------------------------------------------------------------------
diff --git a/maven-core/src/main/java/org/apache/maven/graph/GraphBuilder.java b/maven-core/src/main/java/org/apache/maven/graph/GraphBuilder.java
index fb7c4f2..0f584d9 100644
--- a/maven-core/src/main/java/org/apache/maven/graph/GraphBuilder.java
+++ b/maven-core/src/main/java/org/apache/maven/graph/GraphBuilder.java
@@ -23,6 +23,11 @@ import org.apache.maven.execution.MavenSession;
 import org.apache.maven.execution.ProjectDependencyGraph;
 import org.apache.maven.model.building.Result;
 
+/**
+ * Builds the {@link ProjectDependencyGraph inter-dependencies graph} between projects in
the reactor.
+ *
+ * @since 3.0-alpha
+ */
 public interface GraphBuilder
 {
     String HINT = "graphBuilder";

http://git-wip-us.apache.org/repos/asf/maven/blob/512fa6a4/maven-core/src/site/apt/index.apt
----------------------------------------------------------------------
diff --git a/maven-core/src/site/apt/index.apt b/maven-core/src/site/apt/index.apt
index 966b57c..1e7a68e 100644
--- a/maven-core/src/site/apt/index.apt
+++ b/maven-core/src/site/apt/index.apt
@@ -27,14 +27,25 @@ Maven Core
 
  Maven Core classes managing the whole build process.
 
-* Useful entry points
+* Reference Documentation
 
  * {{{./lifecycles.html}lifecycles}} and {{{./default-bindings.html}plugin bindings to <<<default>>>
lifecycle}},
 
  * {{{./artifact-handlers.html}default artifact handlers}},
 
+ * {{{./extension.html}extension descriptor}} and {{{./core-extensions.html}core extensions}},
+
+ * {{{/guides/mini/guide-maven-classloading.html}classloader hierarchy}} done by <<<ClassRealmManager>>>
component
+ ({{{./apidocs/org/apache/maven/classrealm/ClassRealmManager.html}javadoc}}),
+ with its <<<DefaultClassRealmManager>>> implementation
+ ({{{./xref/org/apache/maven/classrealm/DefaultClassRealmManager.html}source}}), using
+ {{{https://codehaus-plexus.github.io/plexus-classworlds/}Plexus Classworlds}},
+
+* Useful entry points
+
  * <<<Maven>>> component ({{{./apidocs/org/apache/maven/Maven.html}javadoc}}),
- with its <<<DefaultMaven>>> implementation ({{{./xref/org/apache/maven/DefaultMaven.html}source}}),
+ with its <<<DefaultMaven>>> implementation ({{{./xref/org/apache/maven/DefaultMaven.html}source}}),
to drive
+ a full <<<MavenSession>>> execution ({{{./apidocs/org/apache/maven/execution/MavenSession.html}javadoc}}
 
  * <<<ProjectBuilder>>> component ({{{./apidocs/org/apache/maven/project/ProjectBuilder.html}javadoc}}),
  with its <<<DefaultProjectBuilder>>> implementation
@@ -47,14 +58,6 @@ Maven Core
  * {{{./apidocs/org/apache/maven/plugin/PluginParameterExpressionEvaluator.html}PluginParameterExpressionEvaluator}},
used to
  evaluate plugin parameters values during Mojo configuration,
 
- * {{{/guides/mini/guide-maven-classloading.html}classloader hierarchy}} done by <<<ClassRealmManager>>>
component
- ({{{./apidocs/org/apache/maven/classrealm/ClassRealmManager.html}javadoc}}),
- with its <<<DefaultClassRealmManager>>> implementation
- ({{{./xref/org/apache/maven/classrealm/DefaultClassRealmManager.html}source}}), using
- {{{https://codehaus-plexus.github.io/plexus-classworlds/}Plexus Classworlds}},
-
- * {{{./extension.html}extension descriptor}} and {{{./core-extensions.html}core extensions}},
-
  * <<<ExceptionHandler>>> component ({{{./apidocs/org/apache/maven/exception/ExceptionHandler.html}javadoc}}),
  with its <<<DefaultExceptionHandler>>> implementation
  ({{{./xref/org/apache/maven/exception/DefaultExceptionHandler.html}source}}), use to transform
exception into useful end-user messages.

http://git-wip-us.apache.org/repos/asf/maven/blob/512fa6a4/maven-core/src/site/apt/scripting-support/marmalade-support.apt
----------------------------------------------------------------------
diff --git a/maven-core/src/site/apt/scripting-support/marmalade-support.apt b/maven-core/src/site/apt/scripting-support/marmalade-support.apt
deleted file mode 100644
index 7a80966..0000000
--- a/maven-core/src/site/apt/scripting-support/marmalade-support.apt
+++ /dev/null
@@ -1,196 +0,0 @@
-~~ Licensed to the Apache Software Foundation (ASF) under one
-~~ or more contributor license agreements.  See the NOTICE file
-~~ distributed with this work for additional information
-~~ regarding copyright ownership.  The ASF licenses this file
-~~ to you under the Apache License, Version 2.0 (the
-~~ "License"); you may not use this file except in compliance
-~~ with the License.  You may obtain a copy of the License at
-~~
-~~ http://www.apache.org/licenses/LICENSE-2.0
-~~
-~~ Unless required by applicable law or agreed to in writing,
-~~ software distributed under the License is distributed on an
-~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-~~ KIND, either express or implied.  See the License for the
-~~ specific language governing permissions and limitations
-~~ under the License.
-
-  ---
-  Marmalade Mojo Support - Notes
-  ---
-  John Casey
-  ---
-  07-Feb-2005
-  ---
-
-Marmalade Support
-
-*Abstract
-
-  This document will track the design and implementation issues involved in
-  adding support to m2 for marmalade-based mojos.
-
-*Design Notes
-
-  [[1]] <<Marmalade mojo descriptor specification.>>
-
-        As in all mojo specifications, it is ideal that the descriptor for
-        a marmalade-based mojo be inline with the source code. This centralizes
-        all maintenance related to a single mojo to a single point of maintenance.
-
-        The following is what I'm thinking as of now:
-
-        - a marmalade-based mojo should look something like:
-
-+---+
-        <mojo xmlns="m2:mojo" xmlns:marmalade-control="marmalade:marmalade-control" marmalade-control:el="none">
-
-          <metadata>
-            <id>mmld</id>
-            <name>mmldCompile</name>
-            <lifecyclePhase>compile</lifecyclePhase>
-            <description>Used to compile marmalade scripts into java beans.</description>
-
-            <requiresDependencyResolution/>
-            <instantiationStrategy/>
-            <executionStrategy/>
-
-            <parameters>
-
-              <parameter>
-                <name>classpath</name>
-                <description>The compilation classpath</description>
-                <type>java.util.List</type>
-                <expression>#pom.artifacts</expression>
-
-                <required/>
-                <validator/>
-                <default/>
-
-              </parameter>
-
-            </parameters>
-
-          </metadata>
-
-          <execute>
-            <!-- Do some stuff. -->
-          </execute>
-
-        </mojo>
-+---+
-[NOTE] All empty elements above signify optional elements, usage specification.
-
-  [[2]] <<Marmalade mojo packager.>>
-
-        The marmalade mojo packager will:
-
-        [[a]] Locate all *.mmld files within the scripts directory of the project.
-
-              The scripts directory should be tied to the script language within
-              the POM. Until we have multiple language support in the POM, we'll
-              use something like: <<<xpath(build/marmaladeSourceDirectory)>>>.
-
-        [[b]] For each script found:
-
-              [[i]]   Execute the script with "gatherMetadata=true" in the context.
-
-              [[ii]]  Retrieve the mojo descriptor from the resulting "metadata"
-                      variable in the context.
-
-              [[iii]] Cache the mojo descriptor in aggregator for subsequent
-                      output to plugin descriptor file.
-
-        [[c]] Copy all scripts to the target directory. Preserve relative paths.
-
-        [[d]] <<Process Disjoint:>> <Allow other mojo-descriptor collectors
to
-              run, aggregating their descriptors in similar fashion to [b.iii]
-              above.>
-
-        [[e]] Use the project's dependencies and other info to form the plugin
-              descriptor's header (non-mojo-specific info).
-
-        [[f]] Use the PluginGenerator from maven-plugin-tools to generate a
-              META-INF/plexus/plugin.xml to the target directory.
-
-        [[g]] Continue with lifecycle.
-
-              This may include compilation of java helper classes, etc. and
-              plugin-artifact packaging, presumably via 'jar:jar' or similar.
-
-  [[3]] <<Marmalade mojo loader.>>
-
-        The marmalade mojo loader will:
-
-        [[a]] Retrieve the implementation spec (this is the path of the script,
-              relative to the root of the plugin filesystem...jar, etc.) to
-              $path.
-
-        [[b]] Use the context classloader to retrieve a reader to $path.
-
-        [[c]] Build the ScriptBuilder corresponding to the script.
-
-        [[d]] Create a new MarmaladeMojo instance which adapts the mojo calling
-              semantics to the creation/execution of a marmalade script.
-
-              Execution involves:
-
-              [[i]]   Creating a new MarmaladeScript instance.
-
-              [[ii]]  Creating an execution context which references all I/O
-                      from the main Maven execution thread, and embeds:
-
-                      - #request == MavenExecutionRequest
-
-                      - #response == MavenExecutionResponse
-
-                      - Any globally configured environmental constraints, such
-                        as a global preserve-whitespace setting
-
-              [[iii]] Execution of the script using the execution context.
-
-              [[iv]]  Export of the resulting context, minus any surviving input
-                      variables, to the MavenExecutionResponse's out-params.
-
-*Implementation Issues
-
-  [[1]] How do we make Maven smart enough to switch loader implementations based
-        on some sub-type of maven-plugin?
-
-        This is important, since the default mojo loader will not be smart
-        enough to do the job, and embedding this behavior in that loader is not
-        scalable or extensible enough to accommodate future expansion into the
-        realms of jython, groovy, etc...
-
-        <<UPDATE:07-FEB-2005>>
-
-        We'll plan on using some sort of language specification in the mojo
-        descriptor to determine which mojo loader to use, then we'll populate
-        the PluginLoader/PluginManager with a map of known languages->loaders.
-
-  [[2]] How do we make the plugin:install process smart enough to switch
-        generator implementations based on some sub-type of maven-plugin?
-
-        This is closely related to [1] above.
-
-        <<UPDATE:07-FEB-2005>>
-
-        See update in [3].
-
-  [[3]] Do we want to allow mixed-bag plugin implementations?
-
-        These might include a mix of standard-java and marmalade mojos. It
-        strikes me that many  marmalade-based mojos may use beans/tags that are
-        actually adapter classes for other third-party APIs (why they wouldn't
-        implement everything as java mojos in this cases is beyond me). If they
-        have java source inside the plugin source directory, we should probably
-        compile it and bundle it with the plugin scripts; but what if this source
-        also has mojo annotations? This will have implications for [1] and [2]
-        above.
-
-        <<UPDATE:07-FEB-2005>>
-
-        We will plan on allowing this sort of implementation, and simply start
-        by applying all known generators which have a source directory set in
-        the POM (or later, have a <language/> section, maybe). At any rate,
-        helper classes will be allowed for script-based mojos.


Mime
View raw message