maven-docck-plugin-1.0/0000755000175000017500000000000011240605537014776 5ustar twernertwernermaven-docck-plugin-1.0/src/0000755000175000017500000000000011240605537015565 5ustar twernertwernermaven-docck-plugin-1.0/src/site/0000755000175000017500000000000011240605537016531 5ustar twernertwernermaven-docck-plugin-1.0/src/site/site.xml0000644000175000017500000000225411063234277020224 0ustar twernertwerner maven-docck-plugin-1.0/src/site/fml/0000755000175000017500000000000011240605537017307 5ustar twernertwernermaven-docck-plugin-1.0/src/site/fml/faq.fml0000644000175000017500000000355411063234277020567 0ustar twernertwerner Where did the standard came from?

The plugin documentation standard was created to address the frequent complaint of lack of documentation, specifically for the Maven plugins. The standard was based on suggestions made on the Maven dev mailing list with some refinements. It is a community consensus of what basic documentation a Maven plugin should have.

Why do we need a documentation standard?

The standard is not a set of rules but a guide to help plugin developers document their plugins better, for the benefit of the users of the plugin. The standard also reminds the plugin developers of the important details that needs to be documented, to help speed up the adoption of the plugin.

maven-docck-plugin-1.0/src/site/apt/0000755000175000017500000000000011240605537017315 5ustar twernertwernermaven-docck-plugin-1.0/src/site/apt/examples/0000755000175000017500000000000011240605537021133 5ustar twernertwernermaven-docck-plugin-1.0/src/site/apt/examples/file-output.apt0000644000175000017500000000360711063234651024122 0ustar twernertwerner ------ Sending the output to a file ------ ------ 2008-09-14 ------ ~~ 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. ~~ NOTE: For help with the syntax of this file, see: ~~ http://maven.apache.org/doxia/references/apt-format.html Sending the output to a file * Configuring your <<>> You can use the following configuration in your <<>> to run the DOCCK Plugin everytime the project is built and send its output to a file. +---+ ... ... org.apache.maven.plugins maven-docck-plugin 1.0 target/docck-results.txt check ... ... +---+ * From the command-line You can also direct the command-line execution output to a file using: +---+ mvn docck:check -Doutput=target/docck-results.txt +---+ maven-docck-plugin-1.0/src/site/apt/usage.apt0000644000175000017500000001175111063234651021132 0ustar twernertwerner ------ Usage ------ ------ 2008-09-14 ------ ~~ 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. ~~ NOTE: For help with the syntax of this file, see: ~~ http://maven.apache.org/doxia/references/apt-format.html Usage This document is intended to provide instructions for using the Maven DOCCK Plugin. In order for this discussion to be useful, it's critical to cover two topics: Configuring your project's <<>> to run the plugin during every build and using the plugin from the command-line. * Configuring the plugin in <<>> You can use the following configuration in your <<>> to run the DOCCK Plugin everytime the project is built. +---+ ... ... org.apache.maven.plugins maven-docck-plugin 1.0 check ... ... +---+ * Using the plugin from the command-line The DOCCK Plugin is easily executed from the command line since it can run without any parameter configuration. To run the DOCCK Plugin on a project, type: +---+ mvn docck:check +---+ * Sample Output ** Run with no documentation errors +---+ [INFO] Scanning for projects... [INFO] Searching repository for plugin with prefix: 'docck'. [INFO] ---------------------------------------------------------------------------- [INFO] Building Mojo Project [INFO] task-segment: [docck:check] (aggregator-style) [INFO] ---------------------------------------------------------------------------- [INFO] [docck:check] [INFO] Checking project: Mojo Project [INFO] Using 2 extractors. [INFO] Applying extractor for language: java [INFO] Extractor for language: java found 1 mojo descriptors. [INFO] Applying extractor for language: bsh [INFO] Extractor for language: bsh found 0 mojo descriptors. [INFO] No documentation errors were found. [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESSFUL [INFO] ------------------------------------------------------------------------ [INFO] Total time: 3 seconds [INFO] Finished at: Mon Jun 19 16:06:25 CST 2006 [INFO] Final Memory: 3M/7M [INFO] ------------------------------------------------------------------------ +---+ ** Run with documentation errors +---+ [INFO] Scanning for projects... [INFO] Searching repository for plugin with prefix: 'docck'. [INFO] ---------------------------------------------------------------------------- [INFO] Building Mojo Project [INFO] task-segment: [docck:check] (aggregator-style) [INFO] ---------------------------------------------------------------------------- [INFO] [docck:check] [INFO] Checking project: Mojo Project [INFO] Using 2 extractors. [INFO] Applying extractor for language: java [INFO] Extractor for language: java found 1 mojo descriptors. [INFO] Applying extractor for language: bsh [INFO] Extractor for language: bsh found 0 mojo descriptors. [ERROR] The following documentation problems were found: o Maven Documentation Checker Plugin (3 errors) [ERROR] There is no 'index' file in your site directory (in apt|html|xml[.vm] format). [ERROR] There are no example files in your site directory (in apt|html|xml[.vm] format). They should either be called 'example*.(apt|html|xml)[.vm]' or they should be located in the 'examples' directory. [ERROR] Parameter: 'mojoParameter' in mojo: 'check' is missing a description. [INFO] ------------------------------------------------------------------------ [ERROR] BUILD FAILURE [INFO] ------------------------------------------------------------------------ [INFO] Documentation problems were found. Please see the console output above for more information. [INFO] ------------------------------------------------------------------------ [INFO] For more information, run Maven with the -e switch [INFO] ------------------------------------------------------------------------ [INFO] Total time: 3 seconds [INFO] Finished at: Mon Jun 19 15:54:58 CST 2006 [INFO] Final Memory: 3M/7M [INFO] ------------------------------------------------------------------------ +---+ maven-docck-plugin-1.0/src/site/apt/index.apt0000644000175000017500000000573111063234277021142 0ustar twernertwerner ------ Introduction ------ Dennis Lundberg ------ 20 July 2006 ------ ~~ 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. ~~ NOTE: For help with the syntax of this file, see: ~~ http://maven.apache.org/doxia/references/apt-format.html Maven DOCCK Plugin This plugin checks that a project complies with the {{{http://maven.apache.org/guides/development/guide-plugin-documentation.html}Plugin Documentation Standard}}. * Goals Overview * {{{check-mojo.html}docck:check}} Checks a plugin's documentation for the standard minimums. [] * Usage General instructions on how to use the DOCCK Plugin can be found on the {{{usage.html}usage page}}. Some more specific use cases are described in the examples given below. Last but not least, users occasionally contribute additional examples, tips or errata to the {{{http://docs.codehaus.org/display/MAVENUSER/Documentation+Checker+Plugin}plugin's wiki page}}. In case you still have questions regarding the plugin's usage, please have a look at the {{{faq.html}FAQ}} and feel free to contact the {{{mail-lists.html}user mailing list}}. The posts to the mailing list are archived and could already contain the answer to your question as part of an older thread. Hence, it is also worth browsing/searching the {{{mail-lists.html}mail archive}}. If you feel like the plugin is missing a feature or has a defect, you can fill a feature request or bug report in our {{{issue-tracking.html}issue tracker}}. When creating a new issue, please provide a comprehensive description of your concern. Especially for fixing bugs it is crucial that the developers can reproduce your problem. For this reason, entire debug logs, POMs or most preferably little demo projects attached to the issue are very much appreciated. Of course, patches are welcome, too. Contributors can check out the project from our {{{source-repository.html}source repository}} and will find supplementary information in the {{{http://maven.apache.org/guides/development/guide-helping.html}guide to helping with Maven}}. * Examples To provide you with better understanding of some usages of the DOCCK Plugin, you can take a look at the following examples: * {{{examples/file-output.html}Sending the output to a file}} maven-docck-plugin-1.0/src/main/0000755000175000017500000000000011240605537016511 5ustar twernertwernermaven-docck-plugin-1.0/src/main/resources/0000755000175000017500000000000011240605537020523 5ustar twernertwernermaven-docck-plugin-1.0/src/main/resources/log4j.properties0000644000175000017500000000205010625555116023660 0ustar twernertwerner# 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. log4j.rootCategory=INFO, stdout log4j.appender.stdout=org.apache.log4j.ConsoleAppender log4j.appender.stdout.layout=org.apache.log4j.PatternLayout log4j.appender.stdout.layout.ConversionPattern=%5p [%c{1}:%L] %d{ISO8601} - %m%n log4j.logger.org.apache.commons.httpclient=ERROR maven-docck-plugin-1.0/src/main/java/0000755000175000017500000000000011240605537017432 5ustar twernertwernermaven-docck-plugin-1.0/src/main/java/org/0000755000175000017500000000000011240605537020221 5ustar twernertwernermaven-docck-plugin-1.0/src/main/java/org/apache/0000755000175000017500000000000011240605537021442 5ustar twernertwernermaven-docck-plugin-1.0/src/main/java/org/apache/maven/0000755000175000017500000000000011240605537022550 5ustar twernertwernermaven-docck-plugin-1.0/src/main/java/org/apache/maven/plugin/0000755000175000017500000000000011240605537024046 5ustar twernertwernermaven-docck-plugin-1.0/src/main/java/org/apache/maven/plugin/docck/0000755000175000017500000000000011240605537025131 5ustar twernertwerner././@LongLink0000000000000000000000000000014700000000000011567 Lustar rootrootmaven-docck-plugin-1.0/src/main/java/org/apache/maven/plugin/docck/AbstractCheckDocumentationMojo.javamaven-docck-plugin-1.0/src/main/java/org/apache/maven/plugin/docck/AbstractCheckDocumentationMojo.ja0000644000175000017500000004463611063233241033532 0ustar twernertwernerpackage org.apache.maven.plugin.docck; /* * 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. */ import org.apache.commons.httpclient.Credentials; import org.apache.commons.httpclient.HttpClient; import org.apache.commons.httpclient.HttpException; import org.apache.commons.httpclient.UsernamePasswordCredentials; import org.apache.commons.httpclient.auth.AuthScope; import org.apache.commons.httpclient.methods.HeadMethod; import org.apache.commons.httpclient.params.HttpMethodParams; import org.apache.maven.model.IssueManagement; import org.apache.maven.model.License; import org.apache.maven.model.Organization; import org.apache.maven.model.Prerequisites; import org.apache.maven.model.Scm; import org.apache.maven.plugin.AbstractMojo; import org.apache.maven.plugin.MojoExecutionException; import org.apache.maven.plugin.MojoFailureException; import org.apache.maven.plugin.docck.reports.DocumentationReport; import org.apache.maven.plugin.docck.reports.DocumentationReporter; import org.apache.maven.project.MavenProject; import org.apache.maven.settings.Proxy; import org.apache.maven.settings.Settings; import org.apache.maven.shared.model.fileset.FileSet; import org.apache.maven.shared.model.fileset.util.FileSetManager; import org.codehaus.plexus.util.IOUtil; import org.codehaus.plexus.util.StringUtils; import java.io.File; import java.io.FileWriter; import java.io.IOException; import java.net.MalformedURLException; import java.net.URL; import java.util.ArrayList; import java.util.Iterator; import java.util.LinkedHashMap; import java.util.List; import java.util.Map; /** * 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 { private static final int HTTP_STATUS_200 = 200; /** * @parameter default-value="${reactorProjects}" * @readonly * @required */ private List reactorProjects; /** * An optional location where the results will be written to. If this is * not specified the results will be written to the console. * * @parameter expression="${output}" */ private File output; /** * Directory where the site source for the project is located. * * @parameter expression="${siteDirectory}" default-value="src/site" * @todo should be determined programmatically */ protected String siteDirectory; /** * Sets whether this plugin is running in offline or online mode. Also * useful when you don't want to verify http URLs. * * @parameter expression="${settings.offline}" */ private boolean offline; /** * The current user system settings for use in Maven. * * @parameter expression="${settings}" * @required * @readonly */ private Settings settings; private HttpClient httpClient; private FileSetManager fileSetManager = new FileSetManager(); private List validUrls = new ArrayList(); protected AbstractCheckDocumentationMojo() { String httpUserAgent = "maven-docck-plugin/1.x" + " (Java " + System.getProperty( "java.version" ) + "; " + System.getProperty( "os.name" ) + " " + System.getProperty( "os.version" ) + ")"; httpClient = new HttpClient(); final int connectionTimeout = 5000; httpClient.getHttpConnectionManager().getParams().setConnectionTimeout( connectionTimeout ); httpClient.getParams().setParameter( HttpMethodParams.USER_AGENT, httpUserAgent ); } protected List getReactorProjects() { return reactorProjects; } public void execute() throws MojoExecutionException, MojoFailureException { setupProxy(); if ( output != null ) { getLog().info( "Writing documentation check results to: " + output ); } Map reporters = new LinkedHashMap(); boolean hasErrors = false; for ( Iterator it = reactorProjects.iterator(); it.hasNext(); ) { MavenProject project = (MavenProject) it.next(); if ( approveProjectPackaging( project.getPackaging() ) ) { getLog().info( "Checking project: " + project.getName() ); DocumentationReporter reporter = new DocumentationReporter(); checkProject( project, reporter ); if ( !hasErrors && reporter.hasErrors() ) { hasErrors = true; } reporters.put( project, reporter ); } else { getLog().info( "Skipping unsupported project: " + project.getName() ); } } String messages; messages = buildErrorMessages( reporters ); if ( !hasErrors ) { messages += "No documentation errors were found."; } try { writeMessages( messages, hasErrors ); } 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 problems were found. " + logLocation ); } } /** * Setup proxy access if needed. */ private void setupProxy() { Proxy settingsProxy = settings.getActiveProxy(); if ( settingsProxy != null ) { String proxyUsername = settingsProxy.getUsername(); String proxyPassword = settingsProxy.getPassword(); String proxyHost = settingsProxy.getHost(); int proxyPort = settingsProxy.getPort(); if ( StringUtils.isNotEmpty( proxyHost ) ) { httpClient.getHostConfiguration().setProxy( proxyHost, proxyPort ); getLog().info( "Using proxy [" + proxyHost + "] at port [" + proxyPort + "]." ); if ( StringUtils.isNotEmpty( proxyUsername ) ) { getLog().info( "Using proxy user [" + proxyUsername + "]." ); Credentials creds = new UsernamePasswordCredentials( proxyUsername, proxyPassword ); httpClient.getState().setProxyCredentials( new AuthScope( proxyHost, proxyPort ), creds ); httpClient.getParams().setAuthenticationPreemptive( true ); } } } } private String buildErrorMessages( Map reporters ) { String messages = ""; StringBuffer buffer = new StringBuffer(); for ( Iterator it = reporters.entrySet().iterator(); it.hasNext(); ) { Map.Entry entry = (Map.Entry) it.next(); MavenProject project = (MavenProject) entry.getKey(); DocumentationReporter reporter = (DocumentationReporter) entry.getValue(); if ( !reporter.getMessages().isEmpty() ) { buffer.append( "\no " ).append( project.getName() ); buffer.append( " (" ); final int numberOfErrors = reporter.getMessagesByType( DocumentationReport.TYPE_ERROR ).size(); buffer.append( numberOfErrors ).append( " error" ).append( numberOfErrors == 1 ? "" : "s" ); buffer.append( ", " ); final int numberOfWarnings = reporter.getMessagesByType( DocumentationReport.TYPE_WARN ).size(); buffer.append( numberOfWarnings ).append( " warning" ).append( numberOfWarnings == 1 ? "" : "s" ); buffer.append( ")" ); buffer.append( "\n" ); for ( Iterator errorIterator = reporter.getMessages().iterator(); errorIterator.hasNext(); ) { String error = (String) errorIterator.next(); buffer.append( " " ).append( error ).append( "\n" ); } } } if ( buffer.length() > 0 ) { messages = "The following documentation problems were found:\n" + buffer.toString(); } return messages; } protected abstract boolean approveProjectPackaging( String packaging ); /** * Writes the text in messages either to a file or to the console. * * @param messages The message text * @param hasErrors If there were any documentation errors * @throws IOException */ private void writeMessages( String messages, boolean hasErrors ) throws IOException { if ( output != null ) { FileWriter writer = null; try { writer = new FileWriter( output ); writer.write( messages ); writer.flush(); } finally { IOUtil.close( writer ); } } else { if ( hasErrors ) { getLog().error( messages ); } else { getLog().info( messages ); } } } private void checkProject( MavenProject project, DocumentationReporter reporter ) { checkPomRequirements( project, reporter ); checkPackagingSpecificDocumentation( project, reporter ); } private void checkPomRequirements( MavenProject project, DocumentationReporter reporter ) { checkProjectLicenses( project, reporter ); if ( StringUtils.isEmpty( project.getName() ) ) { reporter.error( "pom.xml is missing the tag." ); } if ( StringUtils.isEmpty( project.getDescription() ) ) { reporter.error( "pom.xml is missing the tag." ); } if ( StringUtils.isEmpty( project.getUrl() ) ) { reporter.error( "pom.xml is missing the tag." ); } else { checkURL( project.getUrl(), "project site", reporter ); } if ( project.getIssueManagement() == null ) { reporter.error( "pom.xml is missing the tag." ); } else { IssueManagement issueMngt = project.getIssueManagement(); if ( StringUtils.isEmpty( issueMngt.getUrl() ) ) { reporter.error( "pom.xml is missing the tag in ." ); } else { checkURL( issueMngt.getUrl(), "Issue Management", reporter ); } } if ( project.getPrerequisites() == null ) { reporter.error( "pom.xml is missing the tag." ); } else { Prerequisites prereq = project.getPrerequisites(); if ( StringUtils.isEmpty( prereq.getMaven() ) ) { reporter.error( "pom.xml is missing the / tag." ); } } if ( StringUtils.isEmpty( project.getInceptionYear() ) ) { reporter.error( "pom.xml is missing the tag." ); } if ( project.getMailingLists().size() == 0 ) { reporter.warn( "pom.xml has no / specified." ); } if ( project.getScm() == null ) { reporter.warn( "pom.xml is missing the tag." ); } else { Scm scm = project.getScm(); if ( StringUtils.isEmpty( scm.getConnection() ) && StringUtils.isEmpty( scm.getDeveloperConnection() ) && StringUtils.isEmpty( scm.getUrl() ) ) { reporter.warn( "pom.xml is missing the child tags under the tag." ); } else if ( scm.getUrl() != null ) { checkURL( scm.getUrl(), "scm", reporter ); } } if ( project.getOrganization() == null ) { reporter.error( "pom.xml is missing the tag." ); } else { Organization org = project.getOrganization(); if ( StringUtils.isEmpty( org.getName() ) ) { reporter.error( "pom.xml is missing the / tag." ); } else if ( org.getUrl() != null ) { checkURL( org.getUrl(), org.getName() + " site", reporter ); } } } private void checkProjectLicenses( MavenProject project, DocumentationReporter reporter ) { List licenses = project.getLicenses(); if ( licenses == null || licenses.isEmpty() ) { reporter.error( "pom.xml has no / specified." ); } else { for ( Iterator it = licenses.iterator(); it.hasNext(); ) { License license = (License) it.next(); if ( StringUtils.isEmpty( license.getName() ) ) { reporter.error( "pom.xml is missing the // tag." ); } else { String url = license.getUrl(); if ( StringUtils.isEmpty( url ) ) { reporter.error( "pom.xml is missing the // tag for the license \'" + license.getName() + "\'." ); } else { checkURL( url, "license \'" + license.getName() + "\'", reporter ); } } } } } private String getURLProtocol( String url ) throws MalformedURLException { String protocol; URL licenseUrl = new URL( url ); protocol = licenseUrl.getProtocol(); if ( protocol != null ) { protocol = protocol.toLowerCase(); } return protocol; } private void checkURL( String url, String description, DocumentationReporter reporter ) { try { String protocol = getURLProtocol( url ); if ( protocol.startsWith( "http" ) ) { if ( offline ) { reporter.warn( "Cannot verify " + description + " in offline mode with URL: \'" + url + "\'." ); } else if ( !validUrls.contains( url ) ) { HeadMethod headMethod = new HeadMethod( url ); headMethod.setFollowRedirects( true ); headMethod.setDoAuthentication( false ); try { getLog().debug( "Verifying http url: " + url ); if ( httpClient.executeMethod( headMethod ) != HTTP_STATUS_200 ) { reporter.error( "Cannot reach " + description + " with URL: \'" + url + "\'." ); } else { validUrls.add( url ); } } catch ( HttpException e ) { reporter.error( "Cannot reach " + description + " with URL: \'" + url + "\'.\nError: " + e.getMessage() ); } catch ( IOException e ) { reporter.error( "Cannot reach " + description + " with URL: \'" + url + "\'.\nError: " + e.getMessage() ); } finally { headMethod.releaseConnection(); } } } else { reporter.warn( "Non-HTTP " + description + " URL not verified." ); } } catch ( MalformedURLException e ) { reporter.warn( "The " + description + " appears to have an invalid URL \'" + url + "\'." + " Message: \'" + e.getMessage() + "\'. Trying to access it as a file instead." ); checkFile( url, description, reporter ); } } private void checkFile( String url, String description, DocumentationReporter reporter ) { File licenseFile = new File( url ); if ( !licenseFile.exists() ) { reporter.error( "The " + description + " in file \'" + licenseFile.getPath() + "\' does not exist." ); } } protected abstract void checkPackagingSpecificDocumentation( MavenProject project, DocumentationReporter reporter ); protected boolean findFiles( File siteDirectory, String pattern ) { FileSet fs = new FileSet(); fs.setDirectory( siteDirectory.getAbsolutePath() ); fs.setFollowSymlinks( false ); fs.addInclude( "apt/" + pattern + ".apt" ); fs.addInclude( "apt/" + pattern + ".apt.vm" ); fs.addInclude( "xdoc/" + pattern + ".xml" ); fs.addInclude( "xdoc/" + pattern + ".xml.vm" ); fs.addInclude( "fml/" + pattern + ".fml" ); fs.addInclude( "fml/" + pattern + ".fml.vm" ); fs.addInclude( "resources/" + pattern + ".html" ); fs.addInclude( "resources/" + pattern + ".html.vm" ); String[] includedFiles = fileSetManager.getIncludedFiles( fs ); return includedFiles != null && includedFiles.length > 0; } } maven-docck-plugin-1.0/src/main/java/org/apache/maven/plugin/docck/reports/0000755000175000017500000000000011240605537026627 5ustar twernertwerner././@LongLink0000000000000000000000000000015000000000000011561 Lustar rootrootmaven-docck-plugin-1.0/src/main/java/org/apache/maven/plugin/docck/reports/InfoDocumentationReport.javamaven-docck-plugin-1.0/src/main/java/org/apache/maven/plugin/docck/reports/InfoDocumentationReport.j0000644000175000017500000000217311063234277033630 0ustar twernertwernerpackage org.apache.maven.plugin.docck.reports; /* * 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. */ /** * @author Edwin Punzalan */ public class InfoDocumentationReport extends AbstractDocumentationReport { public InfoDocumentationReport( String message ) { super( message ); } public int getType() { return DocumentationReport.TYPE_INFO; } } ././@LongLink0000000000000000000000000000015100000000000011562 Lustar rootrootmaven-docck-plugin-1.0/src/main/java/org/apache/maven/plugin/docck/reports/ErrorDocumentationReport.javamaven-docck-plugin-1.0/src/main/java/org/apache/maven/plugin/docck/reports/ErrorDocumentationReport.0000644000175000017500000000217611063234277033657 0ustar twernertwernerpackage org.apache.maven.plugin.docck.reports; /* * 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. */ /** * @author Edwin Punzalan */ public class ErrorDocumentationReport extends AbstractDocumentationReport { public ErrorDocumentationReport( String message ) { super( message ); } public int getType() { return DocumentationReport.TYPE_ERROR; } } ././@LongLink0000000000000000000000000000015300000000000011564 Lustar rootrootmaven-docck-plugin-1.0/src/main/java/org/apache/maven/plugin/docck/reports/WarningDocumentationReport.javamaven-docck-plugin-1.0/src/main/java/org/apache/maven/plugin/docck/reports/WarningDocumentationRepor0000644000175000017500000000220111063234277033716 0ustar twernertwernerpackage org.apache.maven.plugin.docck.reports; /* * 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. */ /** * @author Edwin Punzalan */ public class WarningDocumentationReport extends AbstractDocumentationReport { public WarningDocumentationReport( String message ) { super( message ); } public int getType() { return DocumentationReport.TYPE_WARN; } } ././@LongLink0000000000000000000000000000015400000000000011565 Lustar rootrootmaven-docck-plugin-1.0/src/main/java/org/apache/maven/plugin/docck/reports/AbstractDocumentationReport.javamaven-docck-plugin-1.0/src/main/java/org/apache/maven/plugin/docck/reports/AbstractDocumentationRepo0000644000175000017500000000223211063234277033676 0ustar twernertwernerpackage org.apache.maven.plugin.docck.reports; /* * 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. */ /** * @author Edwin Punzalan */ public abstract class AbstractDocumentationReport implements DocumentationReport { private String message; public AbstractDocumentationReport( String message ) { this.message = message; } public String getMessage() { return message; } } ././@LongLink0000000000000000000000000000014600000000000011566 Lustar rootrootmaven-docck-plugin-1.0/src/main/java/org/apache/maven/plugin/docck/reports/DocumentationReporter.javamaven-docck-plugin-1.0/src/main/java/org/apache/maven/plugin/docck/reports/DocumentationReporter.jav0000644000175000017500000000510011063234277033663 0ustar twernertwernerpackage org.apache.maven.plugin.docck.reports; /* * 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. */ import java.util.List; import java.util.ArrayList; import java.util.Iterator; /** * @author Edwin Punzalan */ public class DocumentationReporter { private List reports = new ArrayList(); public void info( String message ) { reports.add( new InfoDocumentationReport( "[INFO] " + message ) ); } public void warn( String message ) { reports.add( new WarningDocumentationReport( "[WARN] " + message ) ); } public void error( String message ) { reports.add( new ErrorDocumentationReport( "[ERROR] " + message ) ); } public List getMessagesByType( int type ) { List list = new ArrayList(); for ( Iterator iter = reports.iterator(); iter.hasNext(); ) { DocumentationReport report = (DocumentationReport) iter.next(); if ( report.getType() == type ) { list.add( report.getMessage() ); } } return list; } public List getMessages() { List list = new ArrayList(); for ( Iterator iter = reports.iterator(); iter.hasNext(); ) { DocumentationReport report = (DocumentationReport) iter.next(); list.add( report.getMessage() ); } return list; } public boolean hasErrors() { for ( Iterator iter = reports.iterator(); iter.hasNext(); ) { DocumentationReport report = (DocumentationReport) iter.next(); if ( report.getType() == DocumentationReport.TYPE_ERROR ) { //first occurrence will do return true; } } return false; } public void clear() { reports.clear(); } } maven-docck-plugin-1.0/src/main/java/org/apache/maven/plugin/docck/reports/DocumentationReport.java0000644000175000017500000000203011063234277033474 0ustar twernertwernerpackage org.apache.maven.plugin.docck.reports; /* * 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. */ /** * @author Edwin Punzalan */ public interface DocumentationReport { int TYPE_INFO = 1; int TYPE_WARN = 2; int TYPE_ERROR = 3; String getMessage(); int getType(); } ././@LongLink0000000000000000000000000000014500000000000011565 Lustar rootrootmaven-docck-plugin-1.0/src/main/java/org/apache/maven/plugin/docck/CheckPluginDocumentationMojo.javamaven-docck-plugin-1.0/src/main/java/org/apache/maven/plugin/docck/CheckPluginDocumentationMojo.java0000644000175000017500000002216211035137445033552 0ustar twernertwernerpackage org.apache.maven.plugin.docck; /* * 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. */ import org.apache.maven.model.ReportPlugin; 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.plugin.docck.reports.DocumentationReporter; import org.apache.maven.project.MavenProject; import org.apache.maven.tools.plugin.extractor.ExtractionException; import org.apache.maven.tools.plugin.scanner.MojoScanner; import org.codehaus.plexus.util.IOUtil; import org.codehaus.plexus.util.ReaderFactory; import java.io.File; import java.io.IOException; import java.io.Reader; import java.util.ArrayList; import java.util.Iterator; import java.util.List; /** * Checks a plugin's documentation for the standard minimums. * * @author jdcasey * @goal check * @aggregator * @phase validate */ public class CheckPluginDocumentationMojo extends AbstractCheckDocumentationMojo { /** * Plexus component that searches for Mojos. * * @component */ protected MojoScanner mojoScanner; // TODO: really a description of length 1 isn't all that helpful... private static final int MIN_DESCRIPTION_LENGTH = 1; protected void checkPackagingSpecificDocumentation( MavenProject project, DocumentationReporter reporter ) { PluginDescriptor descriptor = new PluginDescriptor(); try { mojoScanner.populatePluginDescriptor( project, descriptor ); } catch ( InvalidPluginDescriptorException e ) { reporter.error( "Failed to parse mojo descriptors.\nError: " + e.getMessage() ); descriptor = null; } catch ( ExtractionException e ) { reporter.error( "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(); if ( mojoDescription == null || mojoDescription.trim().length() < MIN_DESCRIPTION_LENGTH ) { reporter.error( "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.getRequirement() == null && param.isEditable() ) { String paramDescription = param.getDescription(); if ( paramDescription == null || paramDescription.trim().length() < MIN_DESCRIPTION_LENGTH ) { reporter.error( "Parameter: \'" + param.getName() + "\' in mojo: \'" + mojo.getGoal() + "\' is missing a description." ); } } } } } } } checkConfiguredReportPlugins( project, reporter ); checkProjectSite( project, reporter ); } protected boolean approveProjectPackaging( String packaging ) { return "maven-plugin".equals( packaging ); } private void checkProjectSite( MavenProject project, DocumentationReporter reporter ) { File projectSiteDirectory = new File( project.getBasedir(), siteDirectory ); // check for site.xml File siteXml = new File( projectSiteDirectory, "site.xml" ); if ( !siteXml.exists() ) { reporter.error( "site.xml is missing." ); } else { Reader streamReader = null; try { streamReader = ReaderFactory.newXmlReader( siteXml ); String siteHtml = IOUtil.toString( streamReader ); if ( siteHtml.indexOf( "href=\"index.html\"" ) < 0 ) { reporter.error( "site.xml is missing the link to: index.html \"Introduction\"." ); } if ( siteHtml.indexOf( "href=\"usage.html\"" ) < 0 ) { reporter.error( "site.xml is missing the link to: usage.html \"Usage\"." ); } if ( siteHtml.indexOf( "href=\"plugin-info.html\"" ) < 0 ) { reporter.error( "site.xml is missing the link to: plugin-info.html \"Goals\"." ); } if ( siteHtml.indexOf( "href=\"faq.html\"" ) < 0 ) { reporter.error( "site.xml is missing the link to: faq.html \"FAQ\"." ); } } catch ( IOException e ) { reporter.error( "Unable to read site.xml file: \'" + siteXml.getAbsolutePath() + "\'.\nError: " + e.getMessage() ); } finally { IOUtil.close( streamReader ); } } // check for index.(apt|html|xml)[.vm] if ( !findFiles( projectSiteDirectory, "index" ) ) { reporter.error( "There is no \'index\' file in your site directory (in apt|html|xml[.vm] format)." ); } // check for usage.(apt|html|xml)[.vm] if ( !findFiles( projectSiteDirectory, "usage" ) ) { reporter.error( "There is no \'usage\' file in your site directory (in apt|html|xml[.vm] format)." ); } // check for **/examples/**.(apt|html|xml)[.vm] or **/example*.(apt|html|xml)[.vm] if ( !findFiles( projectSiteDirectory, "**/examples/*" ) && !findFiles( projectSiteDirectory, "**/example*" ) ) { reporter.error( "There are no example files in your site directory (in apt|html|xml[.vm] format)." + " They should either be called \'example*.(apt|html|xml)[.vm]\'" + " or they should be located in the \'examples\' directory." ); } if ( !findFiles( projectSiteDirectory, "faq" ) ) { reporter.error( "There is no \'faq\' file in your site directory (in apt|fml|html|xml[.vm] format)." ); } } /** * Checks the project configured plugins if the required report plugins are present. * * @param project MavenProject to check * @param reporter listener * @todo maybe this should be checked default for all project? */ private void checkConfiguredReportPlugins( MavenProject project, DocumentationReporter reporter ) { List expectedPlugins = getRequiredPlugins(); List reportPlugins = project.getReportPlugins(); if ( reportPlugins != null && reportPlugins.size() > 0 ) { for ( Iterator plugins = reportPlugins.iterator(); plugins.hasNext(); ) { ReportPlugin plugin = (ReportPlugin) plugins.next(); expectedPlugins.remove( plugin.getArtifactId() ); } } else { reporter.error( "pom.xml has no report plugins configured." ); } for ( Iterator plugins = expectedPlugins.iterator(); plugins.hasNext(); ) { reporter.error( "pom.xml is missing the report plugin: " + plugins.next().toString() + "." ); } } /** * Returns a List of Strings of required report plugins. * * @return List of report plugin artifactIds */ private List getRequiredPlugins() { List list = new ArrayList(); list.add( "maven-javadoc-plugin" ); list.add( "maven-jxr-plugin" ); return list; } } maven-docck-plugin-1.0/pom.xml0000644000175000017500000001173711103421355016314 0ustar twernertwerner 4.0.0 org.apache.maven.plugins maven-plugins 12 maven-docck-plugin 1.0 maven-plugin Maven Documentation Checker Plugin Checks for violations of the Plugin Documentation Standard. 2.0.6 scm:svn:http://svn.apache.org/repos/asf/maven/plugins/tags/maven-docck-plugin-1.0 scm:svn:https://svn.apache.org/repos/asf/maven/plugins/tags/maven-docck-plugin-1.0 http://svn.apache.org/viewvc/maven/plugins/tags/maven-docck-plugin-1.0 jira http://jira.codehaus.org/browse/MDOCCK commons-httpclient commons-httpclient 3.1 commons-logging commons-logging 1.1.1 runtime org.apache.maven.shared file-management 1.0 org.apache.maven.plugin-tools maven-plugin-tools-api 2.4.3 org.apache.maven maven-plugin-descriptor 2.0.6 org.apache.maven.plugin-tools maven-plugin-tools-java 2.4.3 runtime org.apache.maven.plugin-tools maven-plugin-tools-beanshell 2.4.3 runtime org.apache.maven maven-project 2.0.6 org.apache.maven maven-model 2.0.6 org.apache.maven maven-settings 2.0.6 org.apache.maven maven-plugin-api 2.0.6 org.codehaus.plexus plexus-utils 1.5.5 junit junit 3.8.2 test run-its org.apache.maven.plugins maven-antrun-plugin integration-test integration-test NO INTEGRATION TESTS DEFINED run