You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by jd...@apache.org on 2006/04/21 22:19:28 UTC
svn commit: r395994 - in /maven/sandbox/plugins/maven-docck-plugin: ./ src/
src/main/ src/main/java/ src/main/java/org/ src/main/java/org/apache/
src/main/java/org/apache/maven/ src/main/java/org/apache/maven/plugin/
src/main/java/org/apache/maven/plug...
Author: jdcasey
Date: Fri Apr 21 13:19:26 2006
New Revision: 395994
URL: http://svn.apache.org/viewcvs?rev=395994&view=rev
Log:
First pass at a documentation standards-checker plugin.
Added:
maven/sandbox/plugins/maven-docck-plugin/
maven/sandbox/plugins/maven-docck-plugin/pom.xml (with props)
maven/sandbox/plugins/maven-docck-plugin/src/
maven/sandbox/plugins/maven-docck-plugin/src/main/
maven/sandbox/plugins/maven-docck-plugin/src/main/java/
maven/sandbox/plugins/maven-docck-plugin/src/main/java/org/
maven/sandbox/plugins/maven-docck-plugin/src/main/java/org/apache/
maven/sandbox/plugins/maven-docck-plugin/src/main/java/org/apache/maven/
maven/sandbox/plugins/maven-docck-plugin/src/main/java/org/apache/maven/plugin/
maven/sandbox/plugins/maven-docck-plugin/src/main/java/org/apache/maven/plugin/docck/
maven/sandbox/plugins/maven-docck-plugin/src/main/java/org/apache/maven/plugin/docck/AbstractCheckDocumentationMojo.java (with props)
maven/sandbox/plugins/maven-docck-plugin/src/main/java/org/apache/maven/plugin/docck/CheckPluginDocumentationMojo.java (with props)
Added: maven/sandbox/plugins/maven-docck-plugin/pom.xml
URL: http://svn.apache.org/viewcvs/maven/sandbox/plugins/maven-docck-plugin/pom.xml?rev=395994&view=auto
==============================================================================
--- maven/sandbox/plugins/maven-docck-plugin/pom.xml (added)
+++ maven/sandbox/plugins/maven-docck-plugin/pom.xml Fri Apr 21 13:19:26 2006
@@ -0,0 +1,74 @@
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+ <parent>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-plugins</artifactId>
+ <version>1</version>
+ </parent>
+ <artifactId>maven-docck-plugin</artifactId>
+ <packaging>maven-plugin</packaging>
+ <version>1.0-SNAPSHOT</version>
+ <name>Maven Documentation Checker Plugin</name>
+ <url>http://maven.apache.org</url>
+ <dependencies>
+ <dependency>
+ <groupId>commons-httpclient</groupId>
+ <artifactId>commons-httpclient</artifactId>
+ <version>3.0</version>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.maven.shared</groupId>
+ <artifactId>file-management</artifactId>
+ <version>1.0</version>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.maven</groupId>
+ <artifactId>maven-plugin-tools-api</artifactId>
+ <version>2.0.3</version>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.maven</groupId>
+ <artifactId>maven-plugin-descriptor</artifactId>
+ <version>2.0</version>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.maven</groupId>
+ <artifactId>maven-plugin-tools-java</artifactId>
+ <version>2.0.3</version>
+ <scope>runtime</scope>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.maven</groupId>
+ <artifactId>maven-artifact-manager</artifactId>
+ <version>2.0</version>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.maven</groupId>
+ <artifactId>maven-plugin-tools-beanshell</artifactId>
+ <version>2.0.3</version>
+ <scope>runtime</scope>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.maven.reporting</groupId>
+ <artifactId>maven-reporting-impl</artifactId>
+ <version>2.0</version>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.maven</groupId>
+ <artifactId>maven-project</artifactId>
+ <version>2.0</version>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.maven</groupId>
+ <artifactId>maven-plugin-api</artifactId>
+ <version>2.0</version>
+ </dependency>
+ <dependency>
+ <groupId>junit</groupId>
+ <artifactId>junit</artifactId>
+ <version>3.8.1</version>
+ <scope>test</scope>
+ </dependency>
+ </dependencies>
+</project>
Propchange: maven/sandbox/plugins/maven-docck-plugin/pom.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: maven/sandbox/plugins/maven-docck-plugin/pom.xml
------------------------------------------------------------------------------
svn:keywords = "Author Date Id Revision"
Added: maven/sandbox/plugins/maven-docck-plugin/src/main/java/org/apache/maven/plugin/docck/AbstractCheckDocumentationMojo.java
URL: http://svn.apache.org/viewcvs/maven/sandbox/plugins/maven-docck-plugin/src/main/java/org/apache/maven/plugin/docck/AbstractCheckDocumentationMojo.java?rev=395994&view=auto
==============================================================================
--- maven/sandbox/plugins/maven-docck-plugin/src/main/java/org/apache/maven/plugin/docck/AbstractCheckDocumentationMojo.java (added)
+++ maven/sandbox/plugins/maven-docck-plugin/src/main/java/org/apache/maven/plugin/docck/AbstractCheckDocumentationMojo.java Fri Apr 21 13:19:26 2006
@@ -0,0 +1,279 @@
+package org.apache.maven.plugin.docck;
+
+import java.io.File;
+import java.io.FileWriter;
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.Iterator;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+import org.apache.commons.httpclient.HttpClient;
+import org.apache.commons.httpclient.HttpException;
+import org.apache.commons.httpclient.methods.HeadMethod;
+import org.apache.maven.model.License;
+import org.apache.maven.plugin.AbstractMojo;
+import org.apache.maven.plugin.MojoExecutionException;
+import org.apache.maven.plugin.MojoFailureException;
+import org.apache.maven.project.MavenProject;
+import org.apache.maven.shared.model.fileset.FileSet;
+import org.apache.maven.shared.model.fileset.util.FileSetManager;
+import org.codehaus.plexus.util.IOUtil;
+
+/**
+ * Performs the heavy lifting for documentation checks. This is designed to be
+ * reused for other types of projects, too.
+ *
+ * @author jdcasey
+ *
+ */
+public abstract class AbstractCheckDocumentationMojo
+ extends AbstractMojo
+{
+
+ /**
+ * @parameter default-value="${reactorProjects}"
+ * @readonly
+ * @required
+ */
+ private List reactorProjects;
+
+ /**
+ * An optional location where the results should be written.
+ *
+ * @parameter expression="${output}"
+ */
+ private File output;
+
+ private HttpClient httpClient;
+
+ private FileSetManager fileSetManager = new FileSetManager();
+
+ protected AbstractCheckDocumentationMojo()
+ {
+ httpClient = new HttpClient();
+ httpClient.getHttpConnectionManager().getParams().setConnectionTimeout( 5000 );
+ }
+
+ protected List getReactorProjects()
+ {
+ return reactorProjects;
+ }
+
+ public void execute()
+ throws MojoExecutionException, MojoFailureException
+ {
+ if ( output != null )
+ {
+ getLog().info( "Writing documentation survey results to: " + output );
+ }
+
+ Map errors = new LinkedHashMap();
+ boolean hasErrors = false;
+
+ for ( Iterator it = reactorProjects.iterator(); it.hasNext(); )
+ {
+ MavenProject project = (MavenProject) it.next();
+
+ if ( !approveProjectPackaging( project.getPackaging() ) )
+ {
+ getLog().info( "Skipping non-plugin project: " + project.getName() );
+ continue;
+ }
+
+ List projectErrors = checkProject( project );
+
+ hasErrors = hasErrors || !projectErrors.isEmpty();
+
+ errors.put( project, projectErrors );
+ }
+
+ String messages;
+
+ if ( hasErrors )
+ {
+ StringBuffer buffer = new StringBuffer();
+ buffer.append( "\nThe following documentation problems were found:\n" );
+
+ for ( Iterator it = errors.entrySet().iterator(); it.hasNext(); )
+ {
+ Map.Entry entry = (Map.Entry) it.next();
+
+ MavenProject project = (MavenProject) entry.getKey();
+ List projectErrors = (List) entry.getValue();
+
+ if ( !projectErrors.isEmpty() )
+ {
+ buffer.append( "\no " ).append( project.getName() );
+ buffer.append( " (" ).append( projectErrors.size() ).append( " errors)" );
+
+ for ( Iterator errorIterator = projectErrors.iterator(); errorIterator.hasNext(); )
+ {
+ String error = (String) errorIterator.next();
+
+ buffer.append( "\n\t- " ).append( error );
+ }
+
+ buffer.append( "\n" );
+ }
+ }
+
+ messages = buffer.toString();
+ }
+ else
+ {
+ messages = "No documentation errors were found.";
+ }
+
+ try
+ {
+ writeMessages( messages );
+ }
+ catch ( IOException e )
+ {
+ throw new MojoExecutionException( "Error writing results to output file: " + output );
+ }
+
+ if ( hasErrors )
+ {
+ String logLocation;
+ if ( output == null )
+ {
+ logLocation = "Please see the console output above for more information.";
+ }
+ else
+ {
+ logLocation = "Please see \'" + output + "\' for more information.";
+ }
+
+ throw new MojoFailureException( "documentation check", "Documentation errors were found.", logLocation );
+ }
+ }
+
+ protected abstract boolean approveProjectPackaging( String packaging );
+
+ private void writeMessages( String messages )
+ throws IOException
+ {
+ if ( output != null )
+ {
+ FileWriter writer = null;
+
+ try
+ {
+ writer = new FileWriter( output );
+ writer.write( messages );
+ writer.flush();
+ }
+ finally
+ {
+ IOUtil.close( writer );
+ }
+ }
+ else
+ {
+ getLog().info( messages );
+ }
+ }
+
+ private List checkProject( MavenProject project )
+ {
+ List errors = new ArrayList();
+
+ // check for licenses
+ List licenses = project.getLicenses();
+
+ if ( licenses == null || licenses.isEmpty() )
+ {
+ errors.add( "No license(s) specified." );
+ }
+ else
+ {
+ for ( Iterator it = licenses.iterator(); it.hasNext(); )
+ {
+ License license = (License) it.next();
+
+ String url = license.getUrl();
+
+ HeadMethod headMethod = new HeadMethod( url );
+ headMethod.setFollowRedirects( true );
+ headMethod.setDoAuthentication( false );
+
+ try
+ {
+ if ( httpClient.executeMethod( headMethod ) != 200 )
+ {
+ errors.add( "Cannot reach license: " + license.getName() + " with URL: \'" + url + "\'." );
+ }
+ }
+ catch ( HttpException e )
+ {
+ errors.add( "Cannot reach license: " + license.getName() + " with URL: \'" + url + "\'.\nError: "
+ + e.getMessage() );
+ }
+ catch ( IOException e )
+ {
+ errors.add( "Cannot reach license: " + license.getName() + " with URL: \'" + url + "\'.\nError: "
+ + e.getMessage() );
+ }
+ finally
+ {
+ if ( headMethod != null )
+ {
+ headMethod.releaseConnection();
+ }
+ }
+ }
+ }
+
+ File siteDirectory = new File( project.getBasedir(), "src/site" );
+
+ // check for site.xml
+ File siteXml = new File( siteDirectory, "site.xml" );
+
+ if ( !siteXml.exists() )
+ {
+ errors.add( "site.xml is missing." );
+ }
+
+ // check for index.(xml|apt|html)
+ if ( !findFiles( siteDirectory, "index" ) )
+ {
+ errors.add( "Missing site index.(html|xml|apt)." );
+ }
+
+ // check for usage.(xml|apt|html)
+ if ( !findFiles( siteDirectory, "usage" ) )
+ {
+ errors.add( "Missing base usage.(html|xml|apt)." );
+ }
+
+ // check for **/examples/**.(xml|apt|html)
+ if ( !findFiles( siteDirectory, "**/examples/*" ) && !findFiles( siteDirectory, "**/example*" ) )
+ {
+ errors.add( "Missing examples." );
+ }
+
+ checkPackagingSpecificDocumentation( project, errors, siteDirectory );
+
+ return errors;
+ }
+
+ protected abstract void checkPackagingSpecificDocumentation( MavenProject project, List errors, File siteDirectory );
+
+ private boolean findFiles( File siteDirectory, String pattern )
+ {
+ FileSet fs = new FileSet();
+ fs.setDirectory( siteDirectory.getAbsolutePath() );
+ fs.setFollowSymlinks( false );
+
+ fs.addInclude( "apt/" + pattern + ".apt" );
+ fs.addInclude( "xdoc/" + pattern + ".xml" );
+ fs.addInclude( "resources/" + pattern + ".html" );
+
+ String[] includedFiles = fileSetManager.getIncludedFiles( fs );
+
+ return includedFiles != null && includedFiles.length > 0;
+ }
+}
\ No newline at end of file
Propchange: maven/sandbox/plugins/maven-docck-plugin/src/main/java/org/apache/maven/plugin/docck/AbstractCheckDocumentationMojo.java
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: maven/sandbox/plugins/maven-docck-plugin/src/main/java/org/apache/maven/plugin/docck/AbstractCheckDocumentationMojo.java
------------------------------------------------------------------------------
svn:keywords = "Author Date Id Revision"
Added: maven/sandbox/plugins/maven-docck-plugin/src/main/java/org/apache/maven/plugin/docck/CheckPluginDocumentationMojo.java
URL: http://svn.apache.org/viewcvs/maven/sandbox/plugins/maven-docck-plugin/src/main/java/org/apache/maven/plugin/docck/CheckPluginDocumentationMojo.java?rev=395994&view=auto
==============================================================================
--- maven/sandbox/plugins/maven-docck-plugin/src/main/java/org/apache/maven/plugin/docck/CheckPluginDocumentationMojo.java (added)
+++ maven/sandbox/plugins/maven-docck-plugin/src/main/java/org/apache/maven/plugin/docck/CheckPluginDocumentationMojo.java Fri Apr 21 13:19:26 2006
@@ -0,0 +1,119 @@
+package org.apache.maven.plugin.docck;
+
+/*
+ * Copyright 2001-2005 The Apache Software Foundation.
+ *
+ * Licensed 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.
+ */
+
+import java.io.File;
+import java.util.Iterator;
+import java.util.List;
+
+import org.apache.maven.plugin.descriptor.InvalidPluginDescriptorException;
+import org.apache.maven.plugin.descriptor.MojoDescriptor;
+import org.apache.maven.plugin.descriptor.Parameter;
+import org.apache.maven.plugin.descriptor.PluginDescriptor;
+import org.apache.maven.project.MavenProject;
+import org.apache.maven.tools.plugin.extractor.ExtractionException;
+import org.apache.maven.tools.plugin.scanner.MojoScanner;
+
+/**
+ * Checks a plugin's documentation for the standard minimums.
+ *
+ * @goal plugin
+ * @aggregator
+ *
+ * @phase validate
+ *
+ * @author jdcasey
+ */
+public class CheckPluginDocumentationMojo
+ extends AbstractCheckDocumentationMojo
+{
+
+ /**
+ * @component
+ */
+ protected MojoScanner mojoScanner;
+
+ protected void checkPackagingSpecificDocumentation( MavenProject project, List errors, File siteDirectory )
+ {
+ PluginDescriptor descriptor = new PluginDescriptor();
+
+ try
+ {
+ mojoScanner.populatePluginDescriptor( project, descriptor );
+ }
+ catch ( InvalidPluginDescriptorException e )
+ {
+ errors.add( "Failed to parse mojo descriptors.\nError: " + e.getMessage() );
+ descriptor = null;
+ }
+ catch ( ExtractionException e )
+ {
+ errors.add( "Failed to parse mojo descriptors.\nError: " + e.getMessage() );
+ descriptor = null;
+ }
+
+ if ( descriptor != null )
+ {
+ List mojos = descriptor.getMojos();
+
+ // ensure that all mojo classes are documented
+ if ( mojos != null && !mojos.isEmpty() )
+ {
+ for ( Iterator it = mojos.iterator(); it.hasNext(); )
+ {
+ MojoDescriptor mojo = (MojoDescriptor) it.next();
+
+ String mojoDescription = mojo.getDescription();
+
+ // TODO: really a description of length 1 isn't all that helpful...
+ if ( mojoDescription == null || mojoDescription.trim().length() < 1 )
+ {
+ errors.add( "Mojo: \'" + mojo.getGoal() + "\' is missing a description." );
+ }
+
+ List params = mojo.getParameters();
+
+ // ensure that all parameters are documented
+ if ( params != null && !params.isEmpty() )
+ {
+ for ( Iterator paramIterator = params.iterator(); paramIterator.hasNext(); )
+ {
+ Parameter param = (Parameter) paramIterator.next();
+
+ if ( param.isEditable() )
+ {
+ String paramDescription = param.getDescription();
+
+ if ( paramDescription == null || paramDescription.trim().length() < 1 )
+ {
+ errors.add( "Parameter: \'" + param.getName() + "\' in mojo: \'" + mojo.getGoal()
+ + "\' is missing a description." );
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+
+ protected boolean approveProjectPackaging( String packaging )
+ {
+ return "maven-plugin".equals( packaging );
+ }
+
+}
Propchange: maven/sandbox/plugins/maven-docck-plugin/src/main/java/org/apache/maven/plugin/docck/CheckPluginDocumentationMojo.java
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: maven/sandbox/plugins/maven-docck-plugin/src/main/java/org/apache/maven/plugin/docck/CheckPluginDocumentationMojo.java
------------------------------------------------------------------------------
svn:keywords = "Author Date Id Revision"