1 /* 2 * Copyright (c) 1997, 2018, 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 26 package com.sun.tools.javadoc.main; 27 28 import java.io.IOException; 29 import java.util.Collection; 30 import java.util.Locale; 31 32 import javax.tools.JavaFileManager; 33 import javax.tools.JavaFileObject; 34 import javax.tools.StandardJavaFileManager; 35 36 import com.sun.javadoc.*; 37 import com.sun.tools.javac.code.Source.Feature; 38 import com.sun.tools.javac.tree.JCTree.JCClassDecl; 39 import com.sun.tools.javac.util.List; 40 import com.sun.tools.javac.util.ListBuffer; 41 import com.sun.tools.javac.util.Position; 42 43 /** 44 * This class holds the information from one run of javadoc. 45 * Particularly the packages, classes and options specified 46 * by the user. 47 * 48 * <p><b>This is NOT part of any supported API. 49 * If you write code that depends on this, you do so at your own risk. 50 * This code and its internal interfaces are subject to change or 51 * deletion without notice.</b> 52 * 53 * @since 1.2 54 * @author Robert Field 55 * @author Atul M Dambalkar 56 * @author Neal Gafter (rewrite) 57 */ 58 @Deprecated(since="9", forRemoval=true) 59 @SuppressWarnings("removal") 60 public class RootDocImpl extends DocImpl implements RootDoc { 61 62 /** 63 * list of classes specified on the command line. 64 */ 65 private List<ClassDocImpl> cmdLineClasses; 66 67 /** 68 * list of packages specified on the command line. 69 */ 70 private List<PackageDocImpl> cmdLinePackages; 71 72 /** 73 * a collection of all options. 74 */ 75 private List<String[]> options; 76 77 /** 78 * Constructor used when reading source files. 79 * 80 * @param env the documentation environment, state for this javadoc run 81 * @param classes list of classes specified on the commandline 82 * @param packages list of package names specified on the commandline 83 * @param options list of options 84 */ RootDocImpl(DocEnv env, List<JCClassDecl> classes, List<String> packages, List<String[]> options)85 public RootDocImpl(DocEnv env, List<JCClassDecl> classes, List<String> packages, List<String[]> options) { 86 super(env, null); 87 this.options = options; 88 setPackages(env, packages); 89 setClasses(env, classes); 90 } 91 92 /** 93 * Constructor used when reading class files. 94 * 95 * @param env the documentation environment, state for this javadoc run 96 * @param classes list of class names specified on the commandline 97 * @param options list of options 98 */ RootDocImpl(DocEnv env, List<String> classes, List<String[]> options)99 public RootDocImpl(DocEnv env, List<String> classes, List<String[]> options) { 100 super(env, null); 101 this.options = options; 102 cmdLinePackages = List.nil(); 103 ListBuffer<ClassDocImpl> classList = new ListBuffer<>(); 104 for (String className : classes) { 105 ClassDocImpl c = env.loadClass(className); 106 if (c == null) 107 env.error(null, "javadoc.class_not_found", className); 108 else 109 classList = classList.append(c); 110 } 111 cmdLineClasses = classList.toList(); 112 } 113 114 /** 115 * Initialize classes information. Those classes are input from 116 * command line. 117 * 118 * @param env the compilation environment 119 * @param classes a list of ClassDeclaration 120 */ setClasses(DocEnv env, List<JCClassDecl> classes)121 private void setClasses(DocEnv env, List<JCClassDecl> classes) { 122 ListBuffer<ClassDocImpl> result = new ListBuffer<>(); 123 for (JCClassDecl def : classes) { 124 //### Do we want modifier check here? 125 if (env.shouldDocument(def.sym)) { 126 ClassDocImpl cd = env.getClassDoc(def.sym); 127 if (cd != null) { 128 cd.isIncluded = true; 129 result.append(cd); 130 } //else System.out.println(" (classdoc is null)");//DEBUG 131 } //else System.out.println(" (env.shouldDocument() returned false)");//DEBUG 132 } 133 cmdLineClasses = result.toList(); 134 } 135 136 /** 137 * Initialize packages information. 138 * 139 * @param env the compilation environment 140 * @param packages a list of package names (String) 141 */ setPackages(DocEnv env, List<String> packages)142 private void setPackages(DocEnv env, List<String> packages) { 143 ListBuffer<PackageDocImpl> packlist = new ListBuffer<>(); 144 for (String name : packages) { 145 PackageDocImpl pkg = env.lookupPackage(name); 146 if (pkg != null) { 147 pkg.isIncluded = true; 148 packlist.append(pkg); 149 } else { 150 env.warning(null, "main.no_source_files_for_package", name); 151 } 152 } 153 cmdLinePackages = packlist.toList(); 154 } 155 156 /** 157 * Command line options. 158 * 159 * <pre> 160 * For example, given: 161 * javadoc -foo this that -bar other ... 162 * 163 * This method will return: 164 * options()[0][0] = "-foo" 165 * options()[0][1] = "this" 166 * options()[0][2] = "that" 167 * options()[1][0] = "-bar" 168 * options()[1][1] = "other" 169 * </pre> 170 * 171 * @return an array of arrays of String. 172 */ options()173 public String[][] options() { 174 return options.toArray(new String[options.length()][]); 175 } 176 177 /** 178 * Packages specified on the command line. 179 */ specifiedPackages()180 public PackageDoc[] specifiedPackages() { 181 return (PackageDoc[])cmdLinePackages 182 .toArray(new PackageDocImpl[cmdLinePackages.length()]); 183 } 184 185 /** 186 * Classes and interfaces specified on the command line. 187 */ specifiedClasses()188 public ClassDoc[] specifiedClasses() { 189 ListBuffer<ClassDocImpl> classesToDocument = new ListBuffer<>(); 190 for (ClassDocImpl cd : cmdLineClasses) { 191 cd.addAllClasses(classesToDocument, true); 192 } 193 return (ClassDoc[])classesToDocument.toArray(new ClassDocImpl[classesToDocument.length()]); 194 } 195 196 /** 197 * Return all classes and interfaces (including those inside 198 * packages) to be documented. 199 */ classes()200 public ClassDoc[] classes() { 201 ListBuffer<ClassDocImpl> classesToDocument = new ListBuffer<>(); 202 for (ClassDocImpl cd : cmdLineClasses) { 203 cd.addAllClasses(classesToDocument, true); 204 } 205 for (PackageDocImpl pd : cmdLinePackages) { 206 pd.addAllClassesTo(classesToDocument); 207 } 208 return classesToDocument.toArray(new ClassDocImpl[classesToDocument.length()]); 209 } 210 211 /** 212 * Return a ClassDoc for the specified class/interface name 213 * 214 * @param qualifiedName qualified class name 215 * (i.e. includes package name). 216 * 217 * @return a ClassDocImpl holding the specified class, null if 218 * this class is not referenced. 219 */ classNamed(String qualifiedName)220 public ClassDoc classNamed(String qualifiedName) { 221 return env.lookupClass(qualifiedName); 222 } 223 224 /** 225 * Return a PackageDoc for the specified package name 226 * 227 * @param name package name 228 * 229 * @return a PackageDoc holding the specified package, null if 230 * this package is not referenced. 231 */ packageNamed(String name)232 public PackageDoc packageNamed(String name) { 233 return env.lookupPackage(name); 234 } 235 236 /** 237 * Return the name of this Doc item. 238 * 239 * @return the string <code>"*RootDocImpl*"</code>. 240 */ name()241 public String name() { 242 return "*RootDocImpl*"; 243 } 244 245 /** 246 * Return the name of this Doc item. 247 * 248 * @return the string <code>"*RootDocImpl*"</code>. 249 */ qualifiedName()250 public String qualifiedName() { 251 return "*RootDocImpl*"; 252 } 253 254 /** 255 * Return true if this Doc is include in the active set. 256 * RootDocImpl isn't even a program entity so it is always false. 257 */ isIncluded()258 public boolean isIncluded() { 259 return false; 260 } 261 262 /** 263 * Print error message, increment error count. 264 * 265 * @param msg message to print 266 */ printError(String msg)267 public void printError(String msg) { 268 env.printError(msg); 269 } 270 271 /** 272 * Print error message, increment error count. 273 * 274 * @param msg message to print 275 */ printError(SourcePosition pos, String msg)276 public void printError(SourcePosition pos, String msg) { 277 env.printError(pos, msg); 278 } 279 280 /** 281 * Print warning message, increment warning count. 282 * 283 * @param msg message to print 284 */ printWarning(String msg)285 public void printWarning(String msg) { 286 env.printWarning(msg); 287 } 288 289 /** 290 * Print warning message, increment warning count. 291 * 292 * @param msg message to print 293 */ printWarning(SourcePosition pos, String msg)294 public void printWarning(SourcePosition pos, String msg) { 295 env.printWarning(pos, msg); 296 } 297 298 /** 299 * Print a message. 300 * 301 * @param msg message to print 302 */ printNotice(String msg)303 public void printNotice(String msg) { 304 env.printNotice(msg); 305 } 306 307 /** 308 * Print a message. 309 * 310 * @param msg message to print 311 */ printNotice(SourcePosition pos, String msg)312 public void printNotice(SourcePosition pos, String msg) { 313 env.printNotice(pos, msg); 314 } 315 316 /** 317 * Return the path of the overview file and null if it does not exist. 318 * @return the path of the overview file and null if it does not exist. 319 */ getOverviewPath()320 private JavaFileObject getOverviewPath() { 321 for (String[] opt : options) { 322 if (opt[0].equals("-overview")) { 323 if (env.fileManager instanceof StandardJavaFileManager) { 324 StandardJavaFileManager fm = (StandardJavaFileManager) env.fileManager; 325 return fm.getJavaFileObjects(opt[1]).iterator().next(); 326 } 327 } 328 } 329 return null; 330 } 331 332 /** 333 * Do lazy initialization of "documentation" string. 334 */ 335 @Override documentation()336 protected String documentation() { 337 if (documentation == null) { 338 JavaFileObject overviewPath = getOverviewPath(); 339 if (overviewPath == null) { 340 // no doc file to be had 341 documentation = ""; 342 } else { 343 // read from file 344 try { 345 documentation = readHTMLDocumentation( 346 overviewPath.openInputStream(), 347 overviewPath); 348 } catch (IOException exc) { 349 documentation = ""; 350 env.error(null, "javadoc.File_Read_Error", overviewPath.getName()); 351 } 352 } 353 } 354 return documentation; 355 } 356 357 /** 358 * Return the source position of the entity, or null if 359 * no position is available. 360 */ 361 @Override position()362 public SourcePosition position() { 363 JavaFileObject path; 364 return ((path = getOverviewPath()) == null) ? 365 null : 366 SourcePositionImpl.make(path, Position.NOPOS, null); 367 } 368 369 /** 370 * Return the locale provided by the user or the default locale value. 371 */ getLocale()372 public Locale getLocale() { 373 return env.doclocale.locale; 374 } 375 376 /** 377 * Return the current file manager. 378 */ getFileManager()379 public JavaFileManager getFileManager() { 380 return env.fileManager; 381 } 382 initDocLint(Collection<String> opts, Collection<String> customTagNames, String htmlVersion)383 public void initDocLint(Collection<String> opts, Collection<String> customTagNames, 384 String htmlVersion) { 385 env.initDoclint(opts, customTagNames, htmlVersion); 386 } 387 initJavaScriptScanner(boolean allowScriptInComments)388 public JavaScriptScanner initJavaScriptScanner(boolean allowScriptInComments) { 389 return env.initJavaScriptScanner(allowScriptInComments); 390 } 391 isFunctionalInterface(AnnotationDesc annotationDesc)392 public boolean isFunctionalInterface(AnnotationDesc annotationDesc) { 393 return Feature.LAMBDA.allowedInSource(env.source) 394 && annotationDesc.annotationType().qualifiedName().equals( 395 env.syms.functionalInterfaceType.toString()); 396 } 397 showTagMessages()398 public boolean showTagMessages() { 399 return env.showTagMessages(); 400 } 401 } 402