maven-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jdca...@apache.org
Subject 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...
Date Fri, 21 Apr 2006 20:19:28 GMT
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"



Mime
View raw message