maven-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From och...@apache.org
Subject svn commit: r419486 - in /maven/plugins/trunk/maven-jxr-plugin: ./ src/main/java/org/apache/maven/plugin/jxr/ src/site/ src/site/apt/ src/site/apt/examples/ src/site/fml/
Date Thu, 06 Jul 2006 08:21:31 GMT
Author: oching
Date: Thu Jul  6 01:21:30 2006
New Revision: 419486

URL: http://svn.apache.org/viewvc?rev=419486&view=rev
Log:
PR: MJXR-14

Revised and updated plugin documentation to conform with the standard docs.

Added:
    maven/plugins/trunk/maven-jxr-plugin/src/site/apt/examples/
    maven/plugins/trunk/maven-jxr-plugin/src/site/apt/examples/aggregate.apt
    maven/plugins/trunk/maven-jxr-plugin/src/site/apt/examples/linkjavadoc.apt
    maven/plugins/trunk/maven-jxr-plugin/src/site/apt/index.apt
    maven/plugins/trunk/maven-jxr-plugin/src/site/apt/usage.apt
    maven/plugins/trunk/maven-jxr-plugin/src/site/fml/
    maven/plugins/trunk/maven-jxr-plugin/src/site/fml/faq.fml
Modified:
    maven/plugins/trunk/maven-jxr-plugin/pom.xml
    maven/plugins/trunk/maven-jxr-plugin/src/main/java/org/apache/maven/plugin/jxr/AbstractJxrReport.java
    maven/plugins/trunk/maven-jxr-plugin/src/main/java/org/apache/maven/plugin/jxr/JxrReport.java
    maven/plugins/trunk/maven-jxr-plugin/src/main/java/org/apache/maven/plugin/jxr/JxrTestReport.java
    maven/plugins/trunk/maven-jxr-plugin/src/main/java/org/apache/maven/plugin/jxr/PluginLogAdapter.java
    maven/plugins/trunk/maven-jxr-plugin/src/site/site.xml

Modified: maven/plugins/trunk/maven-jxr-plugin/pom.xml
URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-jxr-plugin/pom.xml?rev=419486&r1=419485&r2=419486&view=diff
==============================================================================
--- maven/plugins/trunk/maven-jxr-plugin/pom.xml (original)
+++ maven/plugins/trunk/maven-jxr-plugin/pom.xml Thu Jul  6 01:21:30 2006
@@ -2,7 +2,7 @@
   <parent>
     <artifactId>maven-plugins</artifactId>
     <groupId>org.apache.maven.plugins</groupId>
-    <version>1</version>
+    <version>2-SNAPSHOT</version>
   </parent>
   <modelVersion>4.0.0</modelVersion>
   <artifactId>maven-jxr-plugin</artifactId>
@@ -10,6 +10,9 @@
   <name>Maven JXR Plugin</name>
   <version>2.1-SNAPSHOT</version>
   <inceptionYear>2005</inceptionYear>
+  <prerequisites>
+    <maven>2.0</maven>
+  </prerequisites>
   <developers>
     <developer>
       <name>Fabrice Bellingard</name>
@@ -42,4 +45,12 @@
       <version>1.0-beta-1</version>
     </dependency>
   </dependencies>
+  <reporting>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-changelog-plugin</artifactId>
+      </plugin>
+    </plugins>
+  </reporting>
 </project>

Modified: maven/plugins/trunk/maven-jxr-plugin/src/main/java/org/apache/maven/plugin/jxr/AbstractJxrReport.java
URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-jxr-plugin/src/main/java/org/apache/maven/plugin/jxr/AbstractJxrReport.java?rev=419486&r1=419485&r2=419486&view=diff
==============================================================================
--- maven/plugins/trunk/maven-jxr-plugin/src/main/java/org/apache/maven/plugin/jxr/AbstractJxrReport.java
(original)
+++ maven/plugins/trunk/maven-jxr-plugin/src/main/java/org/apache/maven/plugin/jxr/AbstractJxrReport.java
Thu Jul  6 01:21:30 2006
@@ -133,6 +133,12 @@
      */
     protected boolean aggregate;
 
+    /**
+     * Compiles the list of directories which contain source files that will be included
in the JXR report generation.
+     *
+     * @param sourceDirs    the List of the source directories
+     * @return a List of the directories that will be included in the JXR report generation
+     */
     protected List pruneSourceDirs( List sourceDirs )
     {
         List pruned = new ArrayList( sourceDirs.size() );
@@ -229,6 +235,12 @@
         copyRequiredResources( destinationDirectory );
     }
 
+    /**
+     * Get the bottom text to be displayed at the lower part of the generated JXR reports.
+     *
+     * @param inceptionYear the year when the project was started
+     * @return  a String that contains the bottom text to be displayed in the lower part
of the generrated JXR reports
+     */
     private String getBottomText( String inceptionYear )
     {
         int actualYear = Calendar.getInstance().get( Calendar.YEAR );
@@ -362,6 +374,11 @@
         }
     }
 
+    /**
+     * Gets the list of the source directories to be included in the JXR report generation
+     *
+     * @return a List of the source directories whose contents will be included in the JXR
report generation
+     */
     protected List constructSourceDirs()
     {
         List sourceDirs = new ArrayList( getSourceRoots() );
@@ -382,21 +399,53 @@
         return sourceDirs;
     }
 
+    /**
+     * Cf. overriden method documentation.
+     *
+     * @see org.apache.maven.reporting.AbstractMavenReport#canGenerateReport()
+     */
     public boolean canGenerateReport()
     {
         return canGenerateReport( constructSourceDirs() );
     }
 
+    /**
+     * Cf. overriden method documentation.
+     *
+     * @see org.apache.maven.reporting.AbstractMavenReport#isExternalReport()
+     */
     public boolean isExternalReport()
     {
         return true;
     }
 
+    /**
+     * Abstract method that returns the target directory where the generated JXR reports
will be put.
+     *
+     * @return  a String that contains the target directory name
+     */
     protected abstract String getDestinationDirectory();
 
+    /**
+     * Abstract method that returns the specified source directories that will be included
in the JXR report generation.
+     *
+     * @return a List of the source directories
+     */
     protected abstract List getSourceRoots();
 
+    /**
+     * Abstract method that returns the compile source directories of the specified project
that will be included in the
+     * JXR report generation
+     *
+     * @param project the MavenProject where the JXR report plugin will be executed
+     * @return a List of the source directories
+     */
     protected abstract List getSourceRoots( MavenProject project );
 
+    /**
+     * Abstract method that returns the location of the javadoc files.
+     *
+     * @return a String that contains the loaction of the javadocs
+     */
     protected abstract String getJavadocLocation();
 }

Modified: maven/plugins/trunk/maven-jxr-plugin/src/main/java/org/apache/maven/plugin/jxr/JxrReport.java
URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-jxr-plugin/src/main/java/org/apache/maven/plugin/jxr/JxrReport.java?rev=419486&r1=419485&r2=419486&view=diff
==============================================================================
--- maven/plugins/trunk/maven-jxr-plugin/src/main/java/org/apache/maven/plugin/jxr/JxrReport.java
(original)
+++ maven/plugins/trunk/maven-jxr-plugin/src/main/java/org/apache/maven/plugin/jxr/JxrReport.java
Thu Jul  6 01:21:30 2006
@@ -65,16 +65,25 @@
      */
     private boolean linkJavadoc;
 
+    /**
+     * @see org.apache.maven.plugin.jxr.AbstractJxrReport#getDestinationDirectory()
+     */
     protected String getDestinationDirectory()
     {
         return destDir;
     }
 
+    /**
+     * @see org.apache.maven.plugin.jxr.AbstractJxrReport#getSourceRoots()
+     */
     protected List getSourceRoots()
     {
         return this.sourceDirs;
     }
 
+    /**
+     * @see org.apache.maven.plugin.jxr.AbstractJxrReport#getSourceRoots(org.apache.maven.project.MavenProject)
+     */
     protected List getSourceRoots( MavenProject project )
     {
         return project.getCompileSourceRoots();
@@ -110,6 +119,9 @@
         return "xref/index";
     }
 
+    /**
+     * @see org.apache.maven.plugin.jxr.AbstractJxrReport#getJavadocLocation()
+     */
     protected String getJavadocLocation()
     {
         String location = null;

Modified: maven/plugins/trunk/maven-jxr-plugin/src/main/java/org/apache/maven/plugin/jxr/JxrTestReport.java
URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-jxr-plugin/src/main/java/org/apache/maven/plugin/jxr/JxrTestReport.java?rev=419486&r1=419485&r2=419486&view=diff
==============================================================================
--- maven/plugins/trunk/maven-jxr-plugin/src/main/java/org/apache/maven/plugin/jxr/JxrTestReport.java
(original)
+++ maven/plugins/trunk/maven-jxr-plugin/src/main/java/org/apache/maven/plugin/jxr/JxrTestReport.java
Thu Jul  6 01:21:30 2006
@@ -48,16 +48,25 @@
      */
     private String destDir;
 
+    /**
+     * @see org.apache.maven.plugin.jxr.AbstractJxrReport#getSourceRoots()
+     */
     protected List getSourceRoots()
     {
         return this.sourceDirs;
     }
 
+    /**
+     * @see org.apache.maven.plugin.jxr.AbstractJxrReport#getSourceRoots(org.apache.maven.project.MavenProject)
+     */
     protected List getSourceRoots( MavenProject project )
     {
         return project.getTestCompileSourceRoots();
     }
 
+    /**
+     * @see org.apache.maven.plugin.jxr.AbstractJxrReport#getDestinationDirectory()
+     */
     protected String getDestinationDirectory()
     {
         return destDir;
@@ -93,6 +102,9 @@
         return "xref-test/index";
     }
 
+    /**
+     * @see org.apache.maven.plugin.jxr.AbstractJxrReport#getJavadocLocation()
+     */
     protected String getJavadocLocation()
     {
         // Don't link Javadoc

Modified: maven/plugins/trunk/maven-jxr-plugin/src/main/java/org/apache/maven/plugin/jxr/PluginLogAdapter.java
URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-jxr-plugin/src/main/java/org/apache/maven/plugin/jxr/PluginLogAdapter.java?rev=419486&r1=419485&r2=419486&view=diff
==============================================================================
--- maven/plugins/trunk/maven-jxr-plugin/src/main/java/org/apache/maven/plugin/jxr/PluginLogAdapter.java
(original)
+++ maven/plugins/trunk/maven-jxr-plugin/src/main/java/org/apache/maven/plugin/jxr/PluginLogAdapter.java
Thu Jul  6 01:21:30 2006
@@ -29,26 +29,43 @@
 {
     private final Log log;
 
+    /**
+     * Class constructor
+     *
+     * @param log   the Log object to be used
+     */
     public PluginLogAdapter( Log log )
     {
         this.log = log;
     }
 
+    /**
+     * @see org.apache.maven.jxr.log.Log#info(String)
+     */
     public void info( String string )
     {
         log.info( string );
     }
 
+    /**
+     * @see org.apache.maven.jxr.log.Log#debug(String)
+     */
     public void debug( String string )
     {
         log.debug( string );
     }
 
+    /**
+     * @see org.apache.maven.jxr.log.Log#warn(String)
+     */
     public void warn( String string )
     {
         log.warn( string );
     }
 
+    /**
+     * @see org.apache.maven.jxr.log.Log#error(String)  
+     */
     public void error( String string )
     {
         log.error( string );

Added: maven/plugins/trunk/maven-jxr-plugin/src/site/apt/examples/aggregate.apt
URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-jxr-plugin/src/site/apt/examples/aggregate.apt?rev=419486&view=auto
==============================================================================
--- maven/plugins/trunk/maven-jxr-plugin/src/site/apt/examples/aggregate.apt (added)
+++ maven/plugins/trunk/maven-jxr-plugin/src/site/apt/examples/aggregate.apt Thu Jul  6 01:21:30
2006
@@ -0,0 +1,77 @@
+ ------
+ Aggregating JXR Reports for Multi-Projects
+ ------
+ Maria Odea Ching
+ ------
+ 5 July 2006
+ ------
+
+
+Aggregating JXR Reports for Multi-Projects
+
+ The aggregate parameter of the JXR plugin can be used to generate JXR files for multi-module
projects. Using this parameter,
+ you can opt to generate 1 compiled set of JXR files for the whole project (all modules)
or generate 1 set of JXR files for
+ each module.
+
+ For example, you have the following directory structure:
+
++-----+
+Project
+|-- pom.xml
+|-- Module1
+|   |-- src
+|   |   `-- main
+|   |       `-- java
+|   |           `-- com
+|   |               `-- module1
+|   |                   `-- app
+|   |                       `-- Module1App.java
+|   `-- pom.xml
+|-- Module2
+|   |-- src
+|   |   `-- main
+|   |       `-- java
+|   |           `-- com
+|   |               `-- module2
+|   |                   `-- app
+|   |                       `-- Module2App.java
+|   `-- pom.xml
+`-- Module3
+    |-- src
+    |   `-- main
+    |       `-- java
+    |           `-- com
+    |               `-- module3
+    |                   `-- app
+    |                       `-- Module3App.java
+    `-- pom.xml
++-----+
+
+ And you have the following configuration in your pom.xml:
+
++-----+
+<project>
+  ...
+  <reporting>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-jxr-plugin</artifactId>
+        <configuration>
+          ...
+          <aggregate>true</aggregate>
+          ...
+        </configuration>
+      </plugin>
+    </plugins>
+  ...
+  </reporting>
+  ...
+</project>
++-----+
+
+ When you execute <<<mvn site:site>>> from the parent directory, which
is Project, a set of JXR files will be created
+ in the target directory of Project where all of the JXR files of the project's submodules
are included. Otherwise if
+ the aggregate parameter is set to false, a set of JXR files for Module1 will be generated
in the target directory of
+ Module1, another set of JXR files for Module2 will be generated in the target directory
of Module2, and so on.
+

Added: maven/plugins/trunk/maven-jxr-plugin/src/site/apt/examples/linkjavadoc.apt
URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-jxr-plugin/src/site/apt/examples/linkjavadoc.apt?rev=419486&view=auto
==============================================================================
--- maven/plugins/trunk/maven-jxr-plugin/src/site/apt/examples/linkjavadoc.apt (added)
+++ maven/plugins/trunk/maven-jxr-plugin/src/site/apt/examples/linkjavadoc.apt Thu Jul  6
01:21:30 2006
@@ -0,0 +1,48 @@
+ ------
+ Linking JXR Files to Javadocs
+ ------
+ Maria Odea Ching
+ ------
+ 6 July 2006
+ ------
+
+
+Linking JXR Files to Javadocs
+
+ To link the generated JXR files to the javadocs, you need to set the following JXR plugin
configuration in your pom.xml:
+
++-----+
+<project>
+  ...
+  <reporting>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-javadoc-plugin</artifactId>
+        <configuration>
+          ...
+          <destDir>C:/Project/target/site/javadocs</destDir>
+          ...
+        </configuration>
+      </plugin>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-jxr-plugin</artifactId>
+        <configuration>
+          ...
+          <linkJavadoc>true</linkJavadoc>
+          <javadocDir>C:/Project/target/site/javadocs</javadocDir>
+          ...
+        </configuration>
+      </plugin>
+    </plugins>
+  ...
+  </reporting>
+  ...
+</project>
++-----+
+
+ The generated JXR pages will have a link named "View Javadoc" that will display the javadoc
of the class. In case there
+ were no existing javadocs in the specified javadoc directory and no javadocs will be generated
(meaning no javadoc plugin
+ configuration in the reporting section of the pom), the link will no longer be displayed
even if the linkJavadoc parameter
+ is set to true.
\ No newline at end of file

Added: maven/plugins/trunk/maven-jxr-plugin/src/site/apt/index.apt
URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-jxr-plugin/src/site/apt/index.apt?rev=419486&view=auto
==============================================================================
--- maven/plugins/trunk/maven-jxr-plugin/src/site/apt/index.apt (added)
+++ maven/plugins/trunk/maven-jxr-plugin/src/site/apt/index.apt Thu Jul  6 01:21:30 2006
@@ -0,0 +1,36 @@
+ ------
+ Overview
+ ------
+ Maria Odea Ching
+ ------
+ 4 July 2006
+ ------
+
+
+
+Overview
+
+ The JXR plugin produces a cross-reference of the project's sources. The generated reports
make it easier for the user
+ to reference or find specific lines of code. It is also handy when used with the PMD plugin
for referencing errors found
+ in the code.
+
+
+* Goals Overview
+
+  The JXR plugin has 2 goals:
+
+  * {{{plugin-info.html}jxr:jxr}} is used to generate a cross-reference page of the project's
main sources. The generated JXR
+  files can be linked to the javadocs of the project.
+
+  * {{{plugin-info.html}jxr:test-jxr}} on the other hand, is used to generate a cross-reference
page of the project's test sources.
+
+* Usage
+
+   Some basic instructions for configuring and using the mojos of the <<<maven-jxr-plugin>>>
can be found in
+   the {{{usage.html}Usage guide}}.
+
+* Examples
+
+   Sample use-cases for the plugin are available under the Examples menu.
+
+

Added: maven/plugins/trunk/maven-jxr-plugin/src/site/apt/usage.apt
URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-jxr-plugin/src/site/apt/usage.apt?rev=419486&view=auto
==============================================================================
--- maven/plugins/trunk/maven-jxr-plugin/src/site/apt/usage.apt (added)
+++ maven/plugins/trunk/maven-jxr-plugin/src/site/apt/usage.apt Thu Jul  6 01:21:30 2006
@@ -0,0 +1,79 @@
+ ------
+ How To Use
+ ------
+ Fabrice Bellingard
+ <bellingard.NO-SPAM@gmail.com>
+ Maria Odea Ching
+ ------
+ 5 July 2006
+ ------
+
+How To Use
+
+ The JXR plugin generates a cross-reference of the project's sources. Below are the different
goals and configuration
+ for the plugin.
+
+* Generate JXR as Part of Project Reports
+
+ To include the JXR report in the site generation process, insert the following in the \<reporting\>
section of your
+ pom.xml:
+
++-----+
+<project>
+   ...
+  <build>
+     ...
+  </build>
+
+  <reporting>
+      <plugins>
+          <plugin>
+              <groupId>org.apache.maven.plugins</groupId>
+              <artifactId>maven-jxr-plugin</artifactId>
+          </plugin>
+      </plugins>
+  </reporting>
+   ...
+</project>
++-----+
+
+ The report will be generated when you execute the m2 site plugin.
+
++-----+
+mvn site:site
++-----+
+
+* Explicitly Generate JXR Files
+
+ To explicitly generate JXR files with specific configuration, set the following in the \<build\>
section of your pom.xml:
+
++-----+
+<project>
+   ...
+  <build>
+      <plugins>
+          <plugin>
+              <groupId>org.apache.maven.plugins</groupId>
+              <artifactId>maven-jxr-plugin</artifactId>
+              <configuration>
+                  <bottom>Copyright 2006</bottom>
+                  <docTitle>Maven 2 JXR Plugin Reference</docTitle>
+              </configuration>
+          </plugin>
+      </plugins>
+  </build>
+   ...
+</project>
++-----+
+
+ The JXR files for the project's main sources will be executed using this command:
+
++-----+
+mvn jxr:jxr
++-----+
+
+ To generate JXR files for the project's test sources, execute this command:
+
++-----+
+mvn jxr:test-jxr
++-----+

Added: maven/plugins/trunk/maven-jxr-plugin/src/site/fml/faq.fml
URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-jxr-plugin/src/site/fml/faq.fml?rev=419486&view=auto
==============================================================================
--- maven/plugins/trunk/maven-jxr-plugin/src/site/fml/faq.fml (added)
+++ maven/plugins/trunk/maven-jxr-plugin/src/site/fml/faq.fml Thu Jul  6 01:21:30 2006
@@ -0,0 +1,9 @@
+<?xml version="1.0"?>
+<faqs id="General FAQ">
+  <part id="General">
+    <faq id="1">
+      <question>What is the use of the JXR plugin?</question>
+      <answer><p>The JXR plugin is used to generate cross-reference pages of
the source codes of a project. It is generally used when you want to lookup certain lines
of code using line numbers as reference.</p></answer>
+    </faq>
+  </part>
+</faqs>
\ No newline at end of file

Modified: maven/plugins/trunk/maven-jxr-plugin/src/site/site.xml
URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-jxr-plugin/src/site/site.xml?rev=419486&r1=419485&r2=419486&view=diff
==============================================================================
--- maven/plugins/trunk/maven-jxr-plugin/src/site/site.xml (original)
+++ maven/plugins/trunk/maven-jxr-plugin/src/site/site.xml Thu Jul  6 01:21:30 2006
@@ -11,9 +11,16 @@
     <links>
       <item name="Maven 2" href="http://maven.apache.org"/>
     </links>
-    <menu name="JXR QuickStart">
-      <item name="Overview" href="howto.html"/>
-      <item name="JXR Sample Report" href="example/xref/index.html"/>
+    <menu name="Overview">
+      <item name="Overview" href="index.html"/>
+      <item name="Usage" href="usage.html"/>
+      <item name="FAQs" href="faq.html"/>
+    </menu>
+
+    <menu name="Examples">
+      <item name="Aggregating JXR Reports for Multi-Projects" href="/examples/aggregate.html"/>
+      <item name="Linking JXR Files to Javadocs" href="/examples/linkjavadoc.html"/>
+      <item name="JXR Sample Report" href="/example/xref/index.html"/>
     </menu>
     ${reports}
   </body>



Mime
View raw message