package 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;

     }

 }