Save This Page
Home » openjdk-7 » com.sun.tools.doclets.formats » html » [javadoc | source]
    1   /*
    2    * Copyright (c) 1997, 2011, Oracle and/or its affiliates. All rights reserved.
    3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
    4    *
    5    * This code is free software; you can redistribute it and/or modify it
    6    * under the terms of the GNU General Public License version 2 only, as
    7    * published by the Free Software Foundation.  Oracle designates this
    8    * particular file as subject to the "Classpath" exception as provided
    9    * by Oracle in the LICENSE file that accompanied this code.
   10    *
   11    * This code is distributed in the hope that it will be useful, but WITHOUT
   12    * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
   13    * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
   14    * version 2 for more details (a copy is included in the LICENSE file that
   15    * accompanied this code).
   16    *
   17    * You should have received a copy of the GNU General Public License version
   18    * 2 along with this work; if not, write to the Free Software Foundation,
   19    * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
   20    *
   21    * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
   22    * or visit www.oracle.com if you need additional information or have any
   23    * questions.
   24    */
   25   package com.sun.tools.doclets.formats.html;
   26   
   27   import com.sun.tools.doclets.internal.toolkit;
   28   import com.sun.tools.doclets.internal.toolkit.builders;
   29   import com.sun.tools.doclets.internal.toolkit.util;
   30   
   31   import com.sun.javadoc;
   32   import java.util;
   33   import java.io;
   34   
   35   /**
   36    * The class with "start" method, calls individual Writers.
   37    *
   38    * @author Atul M Dambalkar
   39    * @author Robert Field
   40    * @author Jamie Ho
   41    *
   42    */
   43   public class HtmlDoclet extends AbstractDoclet {
   44       public HtmlDoclet() {
   45           configuration = (ConfigurationImpl) configuration();
   46       }
   47   
   48       /**
   49        * The global configuration information for this run.
   50        */
   51       public ConfigurationImpl configuration;
   52   
   53       /**
   54        * The "start" method as required by Javadoc.
   55        *
   56        * @param root the root of the documentation tree.
   57        * @see com.sun.javadoc.RootDoc
   58        * @return true if the doclet ran without encountering any errors.
   59        */
   60       public static boolean start(RootDoc root) {
   61           try {
   62               HtmlDoclet doclet = new HtmlDoclet();
   63               return doclet.start(doclet, root);
   64           } finally {
   65               ConfigurationImpl.reset();
   66           }
   67       }
   68   
   69       /**
   70        * Create the configuration instance.
   71        * Override this method to use a different
   72        * configuration.
   73        */
   74       public Configuration configuration() {
   75           return ConfigurationImpl.getInstance();
   76       }
   77   
   78       /**
   79        * Start the generation of files. Call generate methods in the individual
   80        * writers, which will in turn genrate the documentation files. Call the
   81        * TreeWriter generation first to ensure the Class Hierarchy is built
   82        * first and then can be used in the later generation.
   83        *
   84        * For new format.
   85        *
   86        * @see com.sun.javadoc.RootDoc
   87        */
   88       protected void generateOtherFiles(RootDoc root, ClassTree classtree)
   89               throws Exception {
   90           super.generateOtherFiles(root, classtree);
   91           if (configuration.linksource) {
   92               if (configuration.destDirName.length() > 0) {
   93                   SourceToHTMLConverter.convertRoot(configuration,
   94                       root, configuration.destDirName + File.separator
   95                       + DocletConstants.SOURCE_OUTPUT_DIR_NAME);
   96               } else {
   97                   SourceToHTMLConverter.convertRoot(configuration,
   98                       root, DocletConstants.SOURCE_OUTPUT_DIR_NAME);
   99               }
  100           }
  101   
  102           if (configuration.topFile.length() == 0) {
  103               configuration.standardmessage.
  104                   error("doclet.No_Non_Deprecated_Classes_To_Document");
  105               return;
  106           }
  107           boolean nodeprecated = configuration.nodeprecated;
  108           String configdestdir = configuration.destDirName;
  109           String confighelpfile = configuration.helpfile;
  110           String configstylefile = configuration.stylesheetfile;
  111           performCopy(configdestdir, confighelpfile);
  112           performCopy(configdestdir, configstylefile);
  113           Util.copyResourceFile(configuration, "inherit.gif", false);
  114           // do early to reduce memory footprint
  115           if (configuration.classuse) {
  116               ClassUseWriter.generate(configuration, classtree);
  117           }
  118           IndexBuilder indexbuilder = new IndexBuilder(configuration, nodeprecated);
  119   
  120           if (configuration.createtree) {
  121               TreeWriter.generate(configuration, classtree);
  122           }
  123           if (configuration.createindex) {
  124               if (configuration.splitindex) {
  125                   SplitIndexWriter.generate(configuration, indexbuilder);
  126               } else {
  127                   SingleIndexWriter.generate(configuration, indexbuilder);
  128               }
  129           }
  130   
  131           if (!(configuration.nodeprecatedlist || nodeprecated)) {
  132               DeprecatedListWriter.generate(configuration);
  133           }
  134   
  135           AllClassesFrameWriter.generate(configuration,
  136               new IndexBuilder(configuration, nodeprecated, true));
  137   
  138           FrameOutputWriter.generate(configuration);
  139   
  140           if (configuration.createoverview) {
  141               PackageIndexWriter.generate(configuration);
  142           }
  143           if (configuration.helpfile.length() == 0 &&
  144               !configuration.nohelp) {
  145               HelpWriter.generate(configuration);
  146           }
  147           // If a stylesheet file is not specified, copy the default stylesheet
  148           // and replace newline with platform-specific newline.
  149           if (configuration.stylesheetfile.length() == 0) {
  150               Util.copyFile(configuration, "stylesheet.css", Util.RESOURCESDIR,
  151                       (configdestdir.isEmpty()) ?
  152                           System.getProperty("user.dir") : configdestdir, false, true);
  153           }
  154       }
  155   
  156       /**
  157        * {@inheritDoc}
  158        */
  159       protected void generateClassFiles(ClassDoc[] arr, ClassTree classtree) {
  160           Arrays.sort(arr);
  161           for(int i = 0; i < arr.length; i++) {
  162               if (!(configuration.isGeneratedDoc(arr[i]) && arr[i].isIncluded())) {
  163                   continue;
  164               }
  165               ClassDoc prev = (i == 0)?
  166                   null:
  167                   arr[i-1];
  168               ClassDoc curr = arr[i];
  169               ClassDoc next = (i+1 == arr.length)?
  170                   null:
  171                   arr[i+1];
  172               try {
  173                   if (curr.isAnnotationType()) {
  174                       AbstractBuilder annotationTypeBuilder =
  175                           configuration.getBuilderFactory()
  176                               .getAnnotationTypeBuilder((AnnotationTypeDoc) curr,
  177                                   prev, next);
  178                       annotationTypeBuilder.build();
  179                   } else {
  180                       AbstractBuilder classBuilder =
  181                           configuration.getBuilderFactory()
  182                               .getClassBuilder(curr, prev, next, classtree);
  183                       classBuilder.build();
  184                   }
  185               } catch (Exception e) {
  186                   e.printStackTrace();
  187                   throw new DocletAbortException();
  188               }
  189           }
  190       }
  191   
  192       /**
  193        * {@inheritDoc}
  194        */
  195       protected void generatePackageFiles(ClassTree classtree) throws Exception {
  196           PackageDoc[] packages = configuration.packages;
  197           if (packages.length > 1) {
  198               PackageIndexFrameWriter.generate(configuration);
  199           }
  200           PackageDoc prev = null, next;
  201           for (int i = 0; i < packages.length; i++) {
  202               // if -nodeprecated option is set and the package is marked as
  203               // deprecated, do not generate the package-summary.html, package-frame.html
  204               // and package-tree.html pages for that package.
  205               if (!(configuration.nodeprecated && Util.isDeprecated(packages[i]))) {
  206                   PackageFrameWriter.generate(configuration, packages[i]);
  207                   next = (i + 1 < packages.length &&
  208                           packages[i + 1].name().length() > 0) ? packages[i + 1] : null;
  209                   //If the next package is unnamed package, skip 2 ahead if possible
  210                   next = (i + 2 < packages.length && next == null) ? packages[i + 2] : next;
  211                   AbstractBuilder packageSummaryBuilder =
  212                           configuration.getBuilderFactory().getPackageSummaryBuilder(
  213                           packages[i], prev, next);
  214                   packageSummaryBuilder.build();
  215                   if (configuration.createtree) {
  216                       PackageTreeWriter.generate(configuration,
  217                               packages[i], prev, next,
  218                               configuration.nodeprecated);
  219                   }
  220                   prev = packages[i];
  221               }
  222           }
  223       }
  224   
  225       /**
  226        * Check for doclet added options here.
  227        *
  228        * @return number of arguments to option. Zero return means
  229        * option not known.  Negative value means error occurred.
  230        */
  231       public static int optionLength(String option) {
  232           // Construct temporary configuration for check
  233           return (ConfigurationImpl.getInstance()).optionLength(option);
  234       }
  235   
  236       /**
  237        * Check that options have the correct arguments here.
  238        * <P>
  239        * This method is not required and will default gracefully
  240        * (to true) if absent.
  241        * <P>
  242        * Printing option related error messages (using the provided
  243        * DocErrorReporter) is the responsibility of this method.
  244        *
  245        * @return true if the options are valid.
  246        */
  247       public static boolean validOptions(String options[][],
  248               DocErrorReporter reporter) {
  249           // Construct temporary configuration for check
  250           return (ConfigurationImpl.getInstance()).validOptions(options, reporter);
  251       }
  252   
  253       private void performCopy(String configdestdir, String filename) {
  254           try {
  255               String destdir = (configdestdir.length() > 0) ?
  256                   configdestdir + File.separatorChar: "";
  257               if (filename.length() > 0) {
  258                   File helpstylefile = new File(filename);
  259                   String parent = helpstylefile.getParent();
  260                   String helpstylefilename = (parent == null)?
  261                       filename:
  262                       filename.substring(parent.length() + 1);
  263                   File desthelpfile = new File(destdir + helpstylefilename);
  264                   if (!desthelpfile.getCanonicalPath().equals(
  265                           helpstylefile.getCanonicalPath())) {
  266                       configuration.message.
  267                           notice((SourcePosition) null,
  268                               "doclet.Copying_File_0_To_File_1",
  269                               helpstylefile.toString(), desthelpfile.toString());
  270                       Util.copyFile(desthelpfile, helpstylefile);
  271                   }
  272               }
  273           } catch (IOException exc) {
  274               configuration.message.
  275                   error((SourcePosition) null,
  276                       "doclet.perform_copy_exception_encountered",
  277                       exc.toString());
  278               throw new DocletAbortException();
  279           }
  280       }
  281   }

Save This Page
Home » openjdk-7 » com.sun.tools.doclets.formats » html » [javadoc | source]