package org.apache.maven.plugin.javadoc;

 /*

  * 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.io.BufferedReader;

 import java.io.File;

 import java.io.IOException;

 import java.io.InputStream;

 import java.io.StringReader;

 import java.io.StringWriter;

 import java.io.Writer;

 import java.lang.reflect.Method;

 import java.net.MalformedURLException;

 import java.net.URL;

 import java.net.URLClassLoader;

 import java.util.ArrayList;

 import java.util.Arrays;

 import java.util.Collections;

 import java.util.Iterator;

 import java.util.LinkedHashMap;

 import java.util.LinkedList;

 import java.util.List;

 import java.util.Locale;

 import java.util.Map;

 import java.util.Properties;

 import java.util.StringTokenizer;

 import java.util.regex.Pattern;

 import org.apache.commons.lang.ClassUtils;

 import org.apache.maven.artifact.Artifact;

 import org.apache.maven.artifact.DependencyResolutionRequiredException;

 import org.apache.maven.artifact.repository.ArtifactRepository;

 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.settings.Settings;

 import org.apache.maven.shared.invoker.MavenInvocationException;

 import org.codehaus.plexus.components.interactivity.InputHandler;

 import org.codehaus.plexus.util.FileUtils;

 import org.codehaus.plexus.util.IOUtil;

 import org.codehaus.plexus.util.ReaderFactory;

 import org.codehaus.plexus.util.StringUtils;

 import org.codehaus.plexus.util.WriterFactory;

 import com.thoughtworks.qdox.JavaDocBuilder;

 import com.thoughtworks.qdox.model.AbstractInheritableJavaEntity;

 import com.thoughtworks.qdox.model.AbstractJavaEntity;

 import com.thoughtworks.qdox.model.Annotation;

 import com.thoughtworks.qdox.model.DocletTag;

 import com.thoughtworks.qdox.model.JavaClass;

 import com.thoughtworks.qdox.model.JavaField;

 import com.thoughtworks.qdox.model.JavaMethod;

 import com.thoughtworks.qdox.model.JavaParameter;

 import com.thoughtworks.qdox.model.Type;

 import com.thoughtworks.qdox.model.TypeVariable;

 import com.thoughtworks.qdox.parser.ParseException;

 /**

  * Abstract class to fix Javadoc documentation and tags in source files.

  * <br/>

  * See <a href="http://download.oracle.com/javase/1.5.0/docs/tooldocs/windows/javadoc.html#wheretags">Where Tags Can Be Used</a>.

  *

  * @author <a href="mailto:vincent.siveton@gmail.com">Vincent Siveton</a>

  * @version $Id$

  * @since 2.6

  */

 public abstract class AbstractFixJavadocMojo

     extends AbstractMojo

 {

     /** The vm line separator */

     private static final String EOL = System.getProperty( "line.separator" );

     /** Tag name for @author **/

     private static final String AUTHOR_TAG = "author";

     /** Tag name for @version **/

     private static final String VERSION_TAG = "version";

     /** Tag name for @since **/

     private static final String SINCE_TAG = "since";

     /** Tag name for @param **/

     private static final String PARAM_TAG = "param";

     /** Tag name for @return **/

     private static final String RETURN_TAG = "return";

     /** Tag name for @throws **/

     private static final String THROWS_TAG = "throws";

     /** Tag name for {@inheritDoc} **/

     private static final String INHERITED_TAG = "{@inheritDoc}";

     /** Start Javadoc String i.e. <code>&#47;&#42;&#42;</code> **/

     private static final String START_JAVADOC = "/**";

     /** End Javadoc String i.e. <code>&#42;&#47;</code> **/

     private static final String END_JAVADOC = "*/";

     /** Javadoc Separator i.e. <code> &#42; </code> **/

     private static final String SEPARATOR_JAVADOC = " * ";

     /** Inherited Javadoc i.e. <code>&#47;&#42;&#42; {&#64;inheritDoc} &#42;&#47;</code> **/

     private static final String INHERITED_JAVADOC = START_JAVADOC + " " + INHERITED_TAG + " " + END_JAVADOC;

     /** <code>all</code> parameter used by {@link #fixTags} **/

     private static final String FIX_TAGS_ALL = "all";

     /** <code>public</code> parameter used by {@link #level} **/

     private static final String LEVEL_PUBLIC = "public";

     /** <code>protected</code> parameter used by {@link #level} **/

     private static final String LEVEL_PROTECTED = "protected";

     /** <code>package</code> parameter used by {@link #level} **/

     private static final String LEVEL_PACKAGE = "package";

     /** <code>private</code> parameter used by {@link #level} **/

     private static final String LEVEL_PRIVATE = "private";

     /** The Clirr Maven plugin groupId <code>org.codehaus.mojo</code> **/

     private static final String CLIRR_MAVEN_PLUGIN_GROUPID = "org.codehaus.mojo";

     /** The Clirr Maven plugin artifactId <code>clirr-maven-plugin</code> **/

     private static final String CLIRR_MAVEN_PLUGIN_ARTIFACTID = "clirr-maven-plugin";

     /** The latest Clirr Maven plugin version <code>2.2.2</code> **/

     private static final String CLIRR_MAVEN_PLUGIN_VERSION = "2.2.2";

     /** The Clirr Maven plugin goal <code>check</code> **/

     private static final String CLIRR_MAVEN_PLUGIN_GOAL = "check";

     // ----------------------------------------------------------------------

     // Mojo components

     // ----------------------------------------------------------------------

     /**

      * Input handler, needed for command line handling.

      *

      * @component

      */

     private InputHandler inputHandler;

     // ----------------------------------------------------------------------

     // Mojo parameters

     // ----------------------------------------------------------------------

     /**

      * Version to compare the current code against using the

      * <a href="http://mojo.codehaus.org/clirr-maven-plugin/">Clirr Maven Plugin</a>.

      * <br/>

      * See <a href="#defaultSince">defaultSince</a>.

      *

      * @parameter expression="${comparisonVersion}" default-value="(,${project.version})"

      */

     private String comparisonVersion;

     /**

      * Default value for the Javadoc tag <code>&#64;author</code>.

      * <br/>

      * If not specified, the <code>user.name</code> defined in the System properties will be used.

      *

      * @parameter expression="${defaultAuthor}"

      */

     private String defaultAuthor;

     /**

      * Default value for the Javadoc tag <code>&#64;since</code>.

      * <br/>

      *

      * @parameter expression="${defaultSince}" default-value="${project.version}"

      */

     private String defaultSince;

     /**

      * Default value for the Javadoc tag <code>&#64;version</code>.

      * <br/>

      * By default, it is <code>&#36;Id:&#36;</code>, corresponding to a

      * <a href="http://svnbook.red-bean.com/en/1.1/ch07s02.html#svn-ch-7-sect-2.3.4">SVN keyword</a>.

      * Refer to your SCM to use an other SCM keyword.

      *

      * @parameter expression="${defaultVersion}"

      */

     private String defaultVersion = "\u0024Id: \u0024"; // can't use default-value="\u0024Id: \u0024"

     /**

      * The file encoding to use when reading the source files. If the property

      * <code>project.build.sourceEncoding</code> is not set, the platform default encoding is used.

      *

      * @parameter expression="${encoding}" default-value="${project.build.sourceEncoding}"

      */

     private String encoding;

     /**

      * Comma separated excludes Java files, i.e. <code>&#42;&#42;/&#42;Test.java</code>.

      *

      * @parameter expression="${excludes}"

      */

     private String excludes;

     /**

      * Comma separated tags to fix in classes, interfaces or methods Javadoc comments.

      * Possible values are:

      * <ul>

      * <li>all (fix all Javadoc tags)</li>

      * <li>author (fix only &#64;author tag)</li>

      * <li>version (fix only &#64;version tag)</li>

      * <li>since (fix only &#64;since tag)</li>

      * <li>param (fix only &#64;param tag)</li>

      * <li>return (fix only &#64;return tag)</li>

      * <li>throws (fix only &#64;throws tag)</li>

      * </ul>

      *

      * @parameter expression="${fixTags}" default-value="all"

      */

     private String fixTags;

     /**

      * Flag to fix the classes or interfaces Javadoc comments according the <code>level</code>.

      *

      * @parameter expression="${fixClassComment}" default-value="true"

      */

     private boolean fixClassComment;

     /**

      * Flag to fix the fields Javadoc comments according the <code>level</code>.

      *

      * @parameter expression="${fixFieldComment}" default-value="true"

      */

     private boolean fixFieldComment;

     /**

      * Flag to fix the methods Javadoc comments according the <code>level</code>.

      *

      * @parameter expression="${fixMethodComment}" default-value="true"

      */

     private boolean fixMethodComment;

     /**

      * Forcing the goal execution i.e. skip warranty messages (not recommended).

      *

      * @parameter expression="${force}"

      */

     private boolean force;

     /**

      * Flag to ignore or not Clirr.

      *

      * @parameter expression="${ignoreClirr}" default-value="false"

      */

     protected boolean ignoreClirr;

     /**

      * Comma separated includes Java files, i.e. <code>&#42;&#42;/&#42;Test.java</code>.

      *

      * @parameter expression="${includes}" default-value="**\/*.java"

      */

     private String includes;

     /**

      * Specifies the access level for classes and members to show in the Javadocs.

      * Possible values are:

      * <ul>

      * <li><a href="http://download.oracle.com/javase/1.4.2/docs/tooldocs/windows/javadoc.html#public">public</a>

      * (shows only public classes and members)</li>

      * <li><a href="http://download.oracle.com/javase/1.4.2/docs/tooldocs/windows/javadoc.html#protected">protected</a>

      * (shows only public and protected classes and members)</li>

      * <li><a href="http://download.oracle.com/javase/1.4.2/docs/tooldocs/windows/javadoc.html#package">package</a>

      * (shows all classes and members not marked private)</li>

      * <li><a href="http://download.oracle.com/javase/1.4.2/docs/tooldocs/windows/javadoc.html#private">private</a>

      * (shows all classes and members)</li>

      * </ul>

      * <br/>

      *

      * @parameter expression="${level}" default-value="protected"

      */

     private String level;

     /**

      * The local repository where the artifacts are located, used by the tests.

      *

      * @parameter expression="${localRepository}"

      */

     private ArtifactRepository localRepository;

     /**

      * Output directory where Java classes will be rewritten.

      *

      * @parameter expression="${outputDirectory}" default-value="${project.build.sourceDirectory}"

      */

     private File outputDirectory;

     /**

      * The Maven Project Object.

      *

      * @parameter expression="${project}"

      * @required

      * @readonly

      */

     private MavenProject project;

     /**

      * The current user system settings for use in Maven.

      *

      * @parameter expression="${settings}"

      * @required

      * @readonly

      */

     private Settings settings;

     // ----------------------------------------------------------------------

     // Internal fields

     // ----------------------------------------------------------------------

     /** The current project class loader. */

     private ClassLoader projectClassLoader;

     /**

      * Split {@link #fixTags} by comma.

      * @see {@link #init()}

      */

     private String[] fixTagsSplitted;

     /** New classes found by Clirr. */

     private List<String> clirrNewClasses;

     /** New Methods in a Class (the key) found by Clirr. */

     private Map<String, List<String>> clirrNewMethods;

     /** List of classes where <code>&#42;since</code> is added. Will be used to add or not this tag in the methods. */

     private List<String> sinceClasses;

     /** {@inheritDoc} */

     public void execute()

         throws MojoExecutionException, MojoFailureException

     {

         if ( !fixClassComment && !fixFieldComment && !fixMethodComment )

         {

             getLog().info( "Specified to NOT fix classes, fields and methods. Nothing to do." );

             return;

         }

         // verify goal params

         init();

         if ( fixTagsSplitted.length == 0 )

         {

             getLog().info( "No fix tag specified. Nothing to do." );

             return;

         }

         // add warranty msg

         if ( !preCheck() )

         {

             return;

         }

         // run clirr

         try

         {

             executeClirr();

         }

         catch ( MavenInvocationException e )

         {

             if ( getLog().isDebugEnabled() )

             {

                 getLog().error( "MavenInvocationException: " + e.getMessage(), e );

             }

             else

             {

                 getLog().error( "MavenInvocationException: " + e.getMessage() );

             }

             getLog().info( "Clirr is ignored." );

         }

         // run qdox and process

         try

         {

             JavaClass[] javaClasses = getQdoxClasses();

             if ( javaClasses != null )

             {

                 for ( int i = 0; i < javaClasses.length; i++ )

                 {

                     JavaClass javaClass = javaClasses[i];

                     processFix( javaClass );

                 }

             }

         }

         catch ( IOException e )

         {

             throw new MojoExecutionException( "IOException: " + e.getMessage(), e );

         }

     }

     // ----------------------------------------------------------------------

     // protected methods

     // ----------------------------------------------------------------------

     /**

      * @param p not null maven project.

      * @return the artifact type.

      */

     protected String getArtifactType( MavenProject p )

     {

         return p.getArtifact().getType();

     }

     /**

      * @param p not null maven project.

      * @return the list of source paths for the given project.

      */

     protected List<String> getProjectSourceRoots( MavenProject p )

     {

         return ( p.getCompileSourceRoots() == null ? Collections.<String>emptyList()

                         : new LinkedList<String>( p.getCompileSourceRoots() ) );

     }

     /**

      * @param p not null

      * @return the compile classpath elements

      * @throws DependencyResolutionRequiredException if any

      */

     protected List<String> getCompileClasspathElements( MavenProject p )

         throws DependencyResolutionRequiredException

     {

         return ( p.getCompileClasspathElements() == null ? Collections.<String>emptyList()

                         : new LinkedList<String>( p.getCompileClasspathElements() ) );

     }

     /**

      * @param javaMethod not null

      * @return the fully qualify name of javaMethod with signature

      */

     protected static String getJavaMethodAsString( JavaMethod javaMethod )

     {

         StringBuffer sb = new StringBuffer();

         sb.append( javaMethod.getParentClass().getFullyQualifiedName() );

         sb.append( "#" ).append( javaMethod.getCallSignature() );

         return sb.toString();

     }

     // ----------------------------------------------------------------------

     // private methods

     // ----------------------------------------------------------------------

     /**

      * Init goal parameters.

      */

     private void init()

     {

         // defaultAuthor

         if ( StringUtils.isEmpty( defaultAuthor ) )

         {

             defaultAuthor = System.getProperty( "user.name" );

         }

         // defaultSince

         int i = defaultSince.indexOf( "-" + Artifact.SNAPSHOT_VERSION );

         if ( i != -1 )

         {

             defaultSince = defaultSince.substring( 0, i );

         }

         // fixTags

         if ( !FIX_TAGS_ALL.equalsIgnoreCase( fixTags.trim() ) )

         {

             String[] split = StringUtils.split( fixTags, "," );

             List<String> filtered = new LinkedList<String>();

             for ( int j = 0; j < split.length; j++ )

             {

                 String s = split[j].trim();

                 if ( JavadocUtil.equalsIgnoreCase( s, FIX_TAGS_ALL, AUTHOR_TAG, VERSION_TAG, SINCE_TAG, PARAM_TAG,

                                                    THROWS_TAG ) )

                 {

                     filtered.add( s );

                 }

                 else

                 {

                     if ( getLog().isWarnEnabled() )

                     {

                         getLog().warn( "Unrecognized '" + s + "' for fixTags parameter. Ignored it!" );

                     }

                 }

             }

             fixTags = StringUtils.join( filtered.iterator(), "," );

         }

         fixTagsSplitted = StringUtils.split( fixTags, "," );

         // encoding

         if ( StringUtils.isEmpty( encoding ) )

         {

             if ( getLog().isWarnEnabled() )

             {

                 getLog().warn(

                                "File encoding has not been set, using platform encoding "

                                    + ReaderFactory.FILE_ENCODING + ", i.e. build is platform dependent!" );

             }

             encoding = ReaderFactory.FILE_ENCODING;

         }

         // level

         level = level.trim();

         if ( !JavadocUtil.equalsIgnoreCase( level, LEVEL_PUBLIC, LEVEL_PROTECTED, LEVEL_PACKAGE, LEVEL_PRIVATE ) )

         {

             if ( getLog().isWarnEnabled() )

             {

                 getLog().warn( "Unrecognized '" + level + "' for level parameter, using 'protected' level." );

             }

             level = "protected";

         }

     }

     /**

      * @return <code>true</code> if the user wants to proceed, <code>false</code> otherwise.

      * @throws MojoExecutionException if any

      */

     private boolean preCheck()

         throws MojoExecutionException

     {

         if ( force )

         {

             return true;

         }

         if ( outputDirectory != null

             && !outputDirectory.getAbsolutePath().equals( getProjectSourceDirectory().getAbsolutePath() ) )

         {

             return true;

         }

         if ( !settings.isInteractiveMode() )

         {

             getLog().error( "Maven is not attempt to interact with the user for input. "

                                 + "Verify the <interactiveMode/> configuration in your settings." );

             return false;

         }

         getLog().warn( "" );

         getLog().warn( "    WARRANTY DISCLAIMER" );

         getLog().warn( "" );

         getLog().warn( "All warranties with regard to this Maven goal are disclaimed!" );

         getLog().warn( "The changes will be done directly in the source code." );

         getLog().warn( "The Maven Team strongly recommends the use of a SCM software BEFORE executing this goal." );

         getLog().warn( "" );

         while ( true )

         {

             getLog().info( "Are you sure to proceed? [Y]es [N]o" );

             try

             {

                 String userExpression = inputHandler.readLine();

                 if ( userExpression == null || JavadocUtil.equalsIgnoreCase( userExpression, "Y", "Yes" ) )

                 {

                     getLog().info( "OK, let's proceed..." );

                     break;

                 }

                 if ( userExpression == null || JavadocUtil.equalsIgnoreCase( userExpression, "N", "No" ) )

                 {

                     getLog().info( "No changes in your sources occur." );

                     return false;

                 }

             }

             catch ( IOException e )

             {

                 throw new MojoExecutionException( "Unable to read from standard input.", e );

             }

         }

         return true;

     }

     /**

      * @return the source dir as File for the given project

      */

     private File getProjectSourceDirectory()

     {

         return new File( project.getBuild().getSourceDirectory() );

     }

     /**

      * Invoke Maven to run clirr-maven-plugin to find API differences.

      *

      * @throws MavenInvocationException if any

      */

     private void executeClirr()

         throws MavenInvocationException

     {

         if ( ignoreClirr )

         {

             getLog().info( "Clirr is ignored." );

             return;

         }

         String clirrGoal = getFullClirrGoal();

         // http://mojo.codehaus.org/clirr-maven-plugin/check-mojo.html

         File clirrTextOutputFile =

             FileUtils.createTempFile( "clirr", ".txt", new File( project.getBuild().getDirectory() ) );

         Properties properties = new Properties();

         properties.put( "textOutputFile", clirrTextOutputFile.getAbsolutePath() );

         properties.put( "comparisonVersion", comparisonVersion );

         properties.put( "failOnError", "false" );

         File invokerDir = new File( project.getBuild().getDirectory(), "invoker" );

         invokerDir.mkdirs();

         File invokerLogFile = FileUtils.createTempFile( "clirr-maven-plugin", ".txt", invokerDir );

         new File( project.getBuild().getDirectory(), "invoker-clirr-maven-plugin.txt" );

         JavadocUtil.invokeMaven( getLog(), new File( localRepository.getBasedir() ), project.getFile(),

                                  Collections.singletonList( clirrGoal ), properties, invokerLogFile );

         try

         {

             if ( invokerLogFile.exists() )

             {

                 String invokerLogContent = StringUtils.unifyLineSeparators( FileUtils.fileRead( invokerLogFile, "UTF-8" ) );

                 // see org.codehaus.mojo.clirr.AbstractClirrMojo#getComparisonArtifact()

                 final String artifactNotFoundMsg =

                     "Unable to find a previous version of the project in the repository";

                 if ( invokerLogContent.indexOf( artifactNotFoundMsg ) != -1 )

                 {

                     getLog().warn( "No previous artifact has been deployed, Clirr is ignored." );

                     return;

                 }

             }

         }

         catch ( IOException e )

         {

             getLog().debug( "IOException: " + e.getMessage() );

         }

         try

         {

             parseClirrTextOutputFile( clirrTextOutputFile );

         }

         catch ( IOException e )

         {

             if ( getLog().isDebugEnabled() )

             {

                 getLog().debug( "IOException: " + e.getMessage(), e );

             }

             getLog().info(

                            "IOException when parsing Clirr output '" + clirrTextOutputFile.getAbsolutePath()

                                + "', Clirr is ignored." );

         }

     }

     /**

      * @param clirrTextOutputFile not null

      * @throws IOException if any

      */

     private void parseClirrTextOutputFile( File clirrTextOutputFile )

         throws IOException

     {

         if ( !clirrTextOutputFile.exists() )

         {

             if ( getLog().isInfoEnabled() )

             {

                 getLog().info(

                                "No Clirr output file '" + clirrTextOutputFile.getAbsolutePath()

                                    + "' exists, Clirr is ignored." );

             }

             return;

         }

         if ( getLog().isInfoEnabled() )

         {

             getLog().info( "Clirr output file was created: " + clirrTextOutputFile.getAbsolutePath() );

         }

         clirrNewClasses = new LinkedList<String>();

         clirrNewMethods = new LinkedHashMap<String, List<String>>();

         BufferedReader input = new BufferedReader( ReaderFactory.newReader( clirrTextOutputFile, "UTF-8" ) );

         String line = null;

         while ( ( line = input.readLine() ) != null )

         {

             String[] split = StringUtils.split( line, ":" );

             if ( split.length != 4 )

             {

                 if ( getLog().isDebugEnabled() )

                 {

                     getLog().debug( "Unable to parse the clirr line: " + line );

                 }

                 continue;

             }

             int code;

             try

             {

                 code = Integer.parseInt( split[1].trim() );

             }

             catch ( NumberFormatException e )

             {

                 if ( getLog().isDebugEnabled() )

                 {

                     getLog().debug( "Unable to parse the clirr line: " + line );

                 }

                 continue;

             }

             // http://clirr.sourceforge.net/clirr-core/exegesis.html

             // 7011 - Method Added

             // 7012 - Method Added to Interface

             // 8000 - Class Added

             List<String> list;

             String[] splits2;

             switch ( code )

             {

                 case 7011:

                     list = clirrNewMethods.get( split[2].trim() );

                     if ( list == null )

                     {

                         list = new ArrayList<String>();

                     }

                     splits2 = StringUtils.split( split[3].trim(), "'" );

                     if ( splits2.length != 3 )

                     {

                         continue;

                     }

                     list.add( splits2[1].trim() );

                     clirrNewMethods.put( split[2].trim(), list );

                     break;

                 case 7012:

                     list = clirrNewMethods.get( split[2].trim() );

                     if ( list == null )

                     {

                         list = new ArrayList<String>();

                     }

                     splits2 = StringUtils.split( split[3].trim(), "'" );

                     if ( splits2.length != 3 )

                     {

                         continue;

                     }

                     list.add( splits2[1].trim() );

                     clirrNewMethods.put( split[2].trim(), list );

                     break;

                 case 8000:

                     clirrNewClasses.add( split[2].trim() );

                     break;

                 default:

                     break;

             }

         }

         if ( clirrNewClasses.isEmpty() && clirrNewMethods.isEmpty() )

         {

             getLog().info( "Clirr NOT found API differences." );

         }

         else

         {

             getLog().info( "Clirr found API differences, i.e. new classes/interfaces or methods." );

         }

     }

     /**

      * @param tag not null

      * @return <code>true</code> if <code>tag</code> is defined in {@link #fixTags}.

      */

     private boolean fixTag( String tag )

     {

         if ( fixTagsSplitted.length == 1 && fixTagsSplitted[0].equals( FIX_TAGS_ALL ) )

         {

             return true;

         }

         for ( int i = 0; i < fixTagsSplitted.length; i++ )

         {

             if ( fixTagsSplitted[i].trim().equals( tag ) )

             {

                 return true;

             }

         }

         return false;

     }

     /**

      * Calling Qdox to find {@link JavaClass} objects from the Maven project sources.

      * Ignore java class if Qdox has parsing errors.

      *

      * @return an array of {@link JavaClass} found by QDox

      * @throws IOException if any

      * @throws MojoExecutionException if any

      */

     private JavaClass[] getQdoxClasses()

         throws IOException, MojoExecutionException

     {

         if ( "pom".equalsIgnoreCase( project.getPackaging() ) )

         {

             getLog().warn( "This project has 'pom' packaging, no Java sources is available." );

             return null;

         }

         List<File> javaFiles = new LinkedList<File>();

         for ( String sourceRoot : getProjectSourceRoots( project ) )

         {

             File f = new File( sourceRoot );

             if ( f.isDirectory() )

             {

                 javaFiles.addAll( FileUtils.getFiles( f, includes, excludes, true ) );

             }

             else

             {

                 if ( getLog().isWarnEnabled() )

                 {

                     getLog().warn( f + " doesn't exist. Ignored it." );

                 }

             }

         }

         JavaDocBuilder builder = new JavaDocBuilder();

         builder.getClassLibrary().addClassLoader( getProjectClassLoader() );

         builder.setEncoding( encoding );

         for ( File f : javaFiles )

         {

             if ( !f.getAbsolutePath().toLowerCase( Locale.ENGLISH ).endsWith( ".java" )

                 && getLog().isWarnEnabled() )

             {

                 getLog().warn( "'" + f + "' is not a Java file. Ignored it." );

                 continue;

             }

             try

             {

                 builder.addSource( f );

             }

             catch ( ParseException e )

             {

                 if ( getLog().isWarnEnabled() )

                 {

                     getLog().warn( "QDOX ParseException: " + e.getMessage() + ". Can't fix it." );

                 }

             }

         }

         return builder.getClasses();

     }

     /**

      * @return the classLoader for the given project using lazy instantiation.

      * @throws MojoExecutionException if any

      */

     private ClassLoader getProjectClassLoader()

         throws MojoExecutionException

     {

         if ( projectClassLoader == null )

         {

             List<String> classPath;

             try

             {

                 classPath = getCompileClasspathElements( project );

             }

             catch ( DependencyResolutionRequiredException e )

             {

                 throw new MojoExecutionException( "DependencyResolutionRequiredException: " + e.getMessage(), e );

             }

             List<URL> urls = new ArrayList<URL>( classPath.size() );

             for ( String filename : classPath )

             {

                 try

                 {

                     urls.add( new File( filename ).toURL() );

                 }

                 catch ( MalformedURLException e )

                 {

                     throw new MojoExecutionException( "MalformedURLException: " + e.getMessage(), e );

                 }

             }

             projectClassLoader = new URLClassLoader( (URL[]) urls.toArray( new URL[urls.size()] ), null );

         }

         return projectClassLoader;

     }

     /**

      * Process the given {@link JavaClass}, ie add missing javadoc tags depending user parameters.

      *

      * @param javaClass not null

      * @throws IOException if any

      * @throws MojoExecutionException if any

      */

     private void processFix( JavaClass javaClass )

         throws IOException, MojoExecutionException

     {

         // Skipping inner classes

         if ( javaClass.isInner() )

         {

             return;

         }

         File javaFile = new File( javaClass.getSource().getURL().getFile() );

         // the original java content in memory

         final String originalContent = StringUtils.unifyLineSeparators( FileUtils.fileRead( javaFile, encoding ) );

         if ( getLog().isDebugEnabled() )

         {

             getLog().debug( "Fixing " + javaClass.getFullyQualifiedName() );

         }

         final StringWriter stringWriter = new StringWriter();

         BufferedReader reader = null;

         try

         {

             reader = new BufferedReader( new StringReader( originalContent ) );

             String line;

             int lineNumber = 0;

             while ( ( line = reader.readLine() ) != null )

             {

                 lineNumber++;

                 final String indent = autodetectIndentation( line );

                 // fixing classes

                 if ( javaClass.getComment() == null && javaClass.getAnnotations() != null

                     && javaClass.getAnnotations().length != 0 )

                 {

                     if ( lineNumber == javaClass.getAnnotations()[0].getLineNumber() )

                     {

                         fixClassComment( stringWriter, originalContent, javaClass, indent );

                         takeCareSingleComment( stringWriter, originalContent, javaClass );

                     }

                 }

                 else

                 {

                     if ( lineNumber == javaClass.getLineNumber() )

                     {

                         fixClassComment( stringWriter, originalContent, javaClass, indent );

                         takeCareSingleComment( stringWriter, originalContent, javaClass );

                     }

                 }

                 // fixing fields

                 if ( javaClass.getFields() != null )

                 {

                     for ( int i = 0; i < javaClass.getFields().length; i++ )

                     {

                         JavaField field = javaClass.getFields()[i];

                         if ( lineNumber == field.getLineNumber() )

                         {

                             fixFieldComment( stringWriter, javaClass, field, indent );

                         }

                     }

                 }

                 // fixing methods

                 if ( javaClass.getMethods() != null )

                 {

                     for ( int i = 0; i < javaClass.getMethods().length; i++ )

                     {

                         JavaMethod method = javaClass.getMethods()[i];

                         if ( lineNumber == method.getLineNumber() )

                         {

                             fixMethodComment( stringWriter, originalContent, method, indent );

                             takeCareSingleComment( stringWriter, originalContent, method );

                         }

                     }

                 }

                 stringWriter.write( line );

                 stringWriter.write( EOL );

             }

         }

         finally

         {

             IOUtil.close( reader );

         }

         if ( getLog().isDebugEnabled() )

         {

             getLog().debug( "Saving " + javaClass.getFullyQualifiedName() );

         }

         if ( outputDirectory != null

             && !outputDirectory.getAbsolutePath().equals( getProjectSourceDirectory().getAbsolutePath() ) )

         {

             String path =

                 StringUtils.replace( javaFile.getAbsolutePath().replaceAll( "\\\\", "/" ),

                                      project.getBuild().getSourceDirectory().replaceAll( "\\\\", "/" ), "" );

             javaFile = new File( outputDirectory, path );

             javaFile.getParentFile().mkdirs();

         }

         writeFile( javaFile, encoding, stringWriter.toString() );

     }

     /**

      * Take care of block or single comments between Javadoc comment and entity declaration ie:

      * <br/>

      * <code>

      * <font color="#808080">1</font>&nbsp;<font color="#ffffff">&nbsp;</font>

      * <font color="#3f5fbf">&#47;&#42;&#42;</font><br />

      * <font color="#808080">2</font>&nbsp;<font color="#ffffff">&nbsp;&nbsp;</font>

      * <font color="#3f5fbf">&#42;&nbsp;{Javadoc&nbsp;Comment}</font><br />

      * <font color="#808080">3</font>&nbsp;<font color="#ffffff">&nbsp;&nbsp;</font>

      * <font color="#3f5fbf">&#42;&#47;</font><br />

      * <font color="#808080">4</font>&nbsp;<font color="#ffffff">&nbsp;</font>

      * <font color="#3f7f5f">&#47;&#42;</font><br />

      * <font color="#808080">5</font>&nbsp;<font color="#ffffff">&nbsp;&nbsp;</font>

      * <font color="#3f7f5f">&#42;&nbsp;{Block&nbsp;Comment}</font><br />

      * <font color="#808080">6</font>&nbsp;<font color="#ffffff">&nbsp;&nbsp;</font>

      * <font color="#3f7f5f">&#42;&#47;</font><br />

      * <font color="#808080">7</font>&nbsp;<font color="#ffffff">&nbsp;</font>

      * <font color="#3f7f5f">&#47;&#47;&nbsp;{Single&nbsp;comment}</font><br />

      * <font color="#808080">8</font>&nbsp;<font color="#ffffff">&nbsp;</font>

      * <font color="#7f0055"><b>public&nbsp;</b></font><font color="#7f0055"><b>void&nbsp;</b></font>

      * <font color="#000000">dummyMethod</font><font color="#000000">(&nbsp;</font>

      * <font color="#000000">String&nbsp;s&nbsp;</font><font color="#000000">){}</font>

      * </code>

      *

      * @param stringWriter not null

      * @param originalContent not null

      * @param entity not null

      * @throws IOException if any

      * @see #extractOriginalJavadoc(String, AbstractJavaEntity)

      */

     private void takeCareSingleComment( final StringWriter stringWriter, final String originalContent,

                                         final AbstractInheritableJavaEntity entity )

         throws IOException

     {

         if ( entity.getComment() == null )

         {

             return;

         }

         String javadocComment = trimRight( extractOriginalJavadoc( originalContent, entity ) );

         String extraComment =

             javadocComment.substring( javadocComment.indexOf( END_JAVADOC ) + END_JAVADOC.length() );

         if ( StringUtils.isNotEmpty( extraComment ) )

         {

             if ( extraComment.indexOf( EOL ) != -1 )

             {

                 stringWriter.write( extraComment.substring( extraComment.indexOf( EOL ) + EOL.length() ) );

             }

             else

             {

                 stringWriter.write( extraComment );

             }

             stringWriter.write( EOL );

         }

     }

     /**

      * Add/update Javadoc class comment.

      *

      * @param stringWriter

      * @param originalContent

      * @param javaClass

      * @param indent

      * @throws MojoExecutionException

      * @throws IOException

      */

     private void fixClassComment( final StringWriter stringWriter, final String originalContent,

                                   final JavaClass javaClass, final String indent )

         throws MojoExecutionException, IOException

     {

         if ( !fixClassComment )

         {

             return;

         }

         if ( !isInLevel( javaClass.getModifiers() ) )

         {

             return;

         }

         // add

         if ( javaClass.getComment() == null )

         {

             addDefaultClassComment( stringWriter, javaClass, indent );

             return;

         }

         // update

         updateEntityComment( stringWriter, originalContent, javaClass, indent );

     }

     /**

      * @param modifiers list of modifiers (public, private, protected, package)

      * @return <code>true</code> if modifier is align with <code>level</code>.

      */

     private boolean isInLevel( String[] modifiers )

     {

         List<String> modifiersAsList = Arrays.asList( modifiers );

         if ( LEVEL_PUBLIC.equalsIgnoreCase( level.trim() ) )

         {

             return modifiersAsList.contains( LEVEL_PUBLIC );

         }

         if ( LEVEL_PROTECTED.equalsIgnoreCase( level.trim() ) )

         {

             return ( modifiersAsList.contains( LEVEL_PUBLIC ) || modifiersAsList.contains( LEVEL_PROTECTED ) );

         }

         if ( LEVEL_PACKAGE.equalsIgnoreCase( level.trim() ) )

         {

             return !modifiersAsList.contains( LEVEL_PRIVATE );

         }

         // should be private (shows all classes and members)

         return true;

     }

     /**

      * Add a default Javadoc for the given class, i.e.:

      * <br/>

      * <code>

      * <font color="#808080">1</font>&nbsp;<font color="#ffffff">&nbsp;</font>

      * <font color="#3f5fbf">&#47;&#42;&#42;</font><br />

      * <font color="#808080">2</font>&nbsp;<font color="#ffffff">&nbsp;&nbsp;</font>

      * <font color="#3f5fbf">&#42;&nbsp;{Comment&nbsp;based&nbsp;on&nbsp;the&nbsp;class&nbsp;name}</font><br />

      * <font color="#808080">3</font>&nbsp;<font color="#ffffff">&nbsp;&nbsp;</font>

      * <font color="#3f5fbf">&#42;</font><br />

      * <font color="#808080">4</font>&nbsp;<font color="#ffffff">&nbsp;&nbsp;</font>

      * <font color="#3f5fbf">&#42;&nbsp;</font><font color="#7f9fbf">@author&nbsp;</font>

      * <font color="#3f5fbf">X&nbsp;{added&nbsp;if&nbsp;addMissingAuthor}</font><br />

      * <font color="#808080">5</font>&nbsp;<font color="#ffffff">&nbsp;&nbsp;</font>

      * <font color="#3f5fbf">&#42;&nbsp;</font><font color="#7f9fbf">@version&nbsp;</font>

      * <font color="#3f5fbf">X&nbsp;{added&nbsp;if&nbsp;addMissingVersion}</font><br />

      * <font color="#808080">6</font>&nbsp;<font color="#ffffff">&nbsp;&nbsp;</font>

      * <font color="#3f5fbf">&#42;&nbsp;</font><font color="#7f9fbf">@since&nbsp;</font>

      * <font color="#3f5fbf">X&nbsp;{added&nbsp;if&nbsp;addMissingSince&nbsp;and&nbsp;new&nbsp;classes

      * from&nbsp;previous&nbsp;version}</font><br />

      * <font color="#808080">7</font>&nbsp;<font color="#ffffff">&nbsp;&nbsp;</font>

      * <font color="#3f5fbf">&#42;&#47;</font><br />

      * <font color="#808080">8</font>&nbsp;<font color="#7f0055"><b>public&nbsp;class&nbsp;</b></font>

      * <font color="#000000">DummyClass&nbsp;</font><font color="#000000">{}</font></code>

      * </code>

      *

      * @param buffer not null

      * @param javaClass not null

      * @param indent not null

      * @see #getDefaultClassJavadocComment(JavaClass)

      * @see #appendDefaultAuthorTag(StringBuffer, String)

      * @see #appendDefaultSinceTag(StringBuffer, String)

      * @see #appendDefaultVersionTag(StringBuffer, String)

      */

     private void addDefaultClassComment( final StringWriter stringWriter, final JavaClass javaClass,

                                          final String indent )

     {

         StringBuffer sb = new StringBuffer();

         sb.append( indent ).append( START_JAVADOC );

         sb.append( EOL );

         sb.append( indent ).append( SEPARATOR_JAVADOC );

         sb.append( getDefaultClassJavadocComment( javaClass ) );

         sb.append( EOL );

         appendSeparator( sb, indent );

         appendDefaultAuthorTag( sb, indent );

         appendDefaultVersionTag( sb, indent );

         if ( fixTag( SINCE_TAG ) )

         {

             if ( !ignoreClirr )

             {

                 if ( isNewClassFromLastVersion( javaClass ) )

                 {

                     appendDefaultSinceTag( sb, indent );

                 }

             }

             else

             {

                 appendDefaultSinceTag( sb, indent );

                 addSinceClasses( javaClass );

             }

         }

         sb.append( indent ).append( " " ).append( END_JAVADOC );

         sb.append( EOL );

         stringWriter.write( sb.toString() );

     }

     /**

      * Add Javadoc field comment, only for static fields or interface fields.

      *

      * @param stringWriter not null

      * @param javaClass not null

      * @param field not null

      * @param indent not null

      * @throws IOException if any

      */

     private void fixFieldComment( final StringWriter stringWriter, final JavaClass javaClass,

                                   final JavaField field, final String indent )

         throws IOException

     {

         if ( !fixFieldComment )

         {

             return;

         }

         if ( !javaClass.isInterface() && ( !isInLevel( field.getModifiers() ) || !field.isStatic() ) )

         {

             return;

         }

         // add

         if ( field.getComment() == null )

         {

             addDefaultFieldComment( stringWriter, field, indent );

             return;

         }

         // no update

     }

     /**

      * Add a default Javadoc for the given field, i.e.:

      * <br/>

      * <code>

      * <font color="#808080">1</font>&nbsp;<font color="#ffffff">&nbsp;&nbsp;&nbsp;&nbsp;</font>

      * <font color="#3f5fbf">&#47;&#42;&#42;&nbsp;Constant&nbsp;</font><font color="#7f7f9f">&lt;code&gt;</font>

      * <font color="#3f5fbf">MY_STRING_CONSTANT=&#34;value&#34;</font>

      * <font color="#7f7f9f">&lt;/code&gt;&nbsp;</font><font color="#3f5fbf">&#42;&#47;</font><br />

      * <font color="#808080">2</font>&nbsp;<font color="#ffffff">&nbsp;&nbsp;&nbsp;&nbsp;</font>

      * <font color="#7f0055"><b>public&nbsp;static&nbsp;final&nbsp;</b></font>

      * <font color="#000000">String&nbsp;MY_STRING_CONSTANT&nbsp;=&nbsp;</font>

      * <font color="#2a00ff">&#34;value&#34;</font><font color="#000000">;</font>

      * </code>

      *

      * @param stringWriter not null

      * @param field not null

      * @param indent not null

      * @throws IOException if any

      */

     private void addDefaultFieldComment( final StringWriter stringWriter, final JavaField field,

                                          final String indent )

         throws IOException

     {

         StringBuffer sb = new StringBuffer();

         sb.append( indent ).append( START_JAVADOC ).append( " " );

         sb.append( "Constant <code>" ).append( field.getName() );

         if ( StringUtils.isNotEmpty( field.getInitializationExpression() ) )

         {

             String qualifiedName = field.getType().getJavaClass().getFullyQualifiedName();

             if ( qualifiedName.equals( Byte.TYPE.toString() ) || qualifiedName.equals( Short.TYPE.toString() )

                 || qualifiedName.equals( Integer.TYPE.toString() ) || qualifiedName.equals( Long.TYPE.toString() )

                 || qualifiedName.equals( Float.TYPE.toString() ) || qualifiedName.equals( Double.TYPE.toString() )

                 || qualifiedName.equals( Boolean.TYPE.toString() )

                 || qualifiedName.equals( Character.TYPE.toString() ) )

             {

                 sb.append( "=" );

                 sb.append( field.getInitializationExpression().trim() );

             }

             if ( qualifiedName.equals( String.class.getName() ) )

             {

                 StringBuffer value = new StringBuffer();

                 String[] lines = getLines( field.getInitializationExpression() );

                 for ( int i = 0; i < lines.length; i++ )

                 {

                     String line = lines[i];

                     StringTokenizer token = new StringTokenizer( line.trim(), "\"\n\r" );

                     while ( token.hasMoreTokens() )

                     {

                         String s = token.nextToken();

                         if ( s.trim().equals( "+" ) )

                         {

                             continue;

                         }

                         if ( s.trim().endsWith( "\\" ) )

                         {

                             s += "\"";

                         }

                         value.append( s );

                     }

                 }

                 sb.append( "=\"" );

                 // reduce the size

                 if ( value.length() < 40 )

                 {

                     sb.append( value.toString() ).append( "\"" );

                 }

                 else

                 {

                     sb.append( value.toString().substring( 0, 39 ) ).append( "\"{trunked}" );

                 }

             }

         }

         sb.append( "</code> " ).append( END_JAVADOC );

         sb.append( EOL );