Sat, 13 Apr 2013 18:48:29 -0700
8009686: Generated javadoc documentation should be able to display type annotation on an array
Reviewed-by: jjg
1 /*
2 * Copyright (c) 1998, 2013, 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 */
26 package com.sun.tools.doclets.formats.html;
28 import java.net.*;
29 import java.util.*;
31 import javax.tools.JavaFileManager;
33 import com.sun.javadoc.*;
34 import com.sun.tools.doclets.internal.toolkit.*;
35 import com.sun.tools.doclets.internal.toolkit.util.*;
36 import com.sun.tools.doclint.DocLint;
37 import com.sun.tools.javac.file.JavacFileManager;
38 import com.sun.tools.javac.util.Context;
39 import com.sun.tools.javadoc.RootDocImpl;
41 /**
42 * Configure the output based on the command line options.
43 * <p>
44 * Also determine the length of the command line option. For example,
45 * for a option "-header" there will be a string argument associated, then the
46 * the length of option "-header" is two. But for option "-nohelp" no argument
47 * is needed so it's length is 1.
48 * </p>
49 * <p>
50 * Also do the error checking on the options used. For example it is illegal to
51 * use "-helpfile" option when already "-nohelp" option is used.
52 * </p>
53 *
54 * <p><b>This is NOT part of any supported API.
55 * If you write code that depends on this, you do so at your own risk.
56 * This code and its internal interfaces are subject to change or
57 * deletion without notice.</b>
58 *
59 * @author Robert Field.
60 * @author Atul Dambalkar.
61 * @author Jamie Ho
62 * @author Bhavesh Patel (Modified)
63 */
64 public class ConfigurationImpl extends Configuration {
66 /**
67 * The build date. Note: For now, we will use
68 * a version number instead of a date.
69 */
70 public static final String BUILD_DATE = System.getProperty("java.version");
72 /**
73 * Argument for command line option "-header".
74 */
75 public String header = "";
77 /**
78 * Argument for command line option "-packagesheader".
79 */
80 public String packagesheader = "";
82 /**
83 * Argument for command line option "-footer".
84 */
85 public String footer = "";
87 /**
88 * Argument for command line option "-doctitle".
89 */
90 public String doctitle = "";
92 /**
93 * Argument for command line option "-windowtitle".
94 */
95 public String windowtitle = "";
97 /**
98 * Argument for command line option "-top".
99 */
100 public String top = "";
102 /**
103 * Argument for command line option "-bottom".
104 */
105 public String bottom = "";
107 /**
108 * Argument for command line option "-helpfile".
109 */
110 public String helpfile = "";
112 /**
113 * Argument for command line option "-stylesheetfile".
114 */
115 public String stylesheetfile = "";
117 /**
118 * Argument for command line option "-Xdocrootparent".
119 */
120 public String docrootparent = "";
122 /**
123 * True if command line option "-nohelp" is used. Default value is false.
124 */
125 public boolean nohelp = false;
127 /**
128 * True if command line option "-splitindex" is used. Default value is
129 * false.
130 */
131 public boolean splitindex = false;
133 /**
134 * False if command line option "-noindex" is used. Default value is true.
135 */
136 public boolean createindex = true;
138 /**
139 * True if command line option "-use" is used. Default value is false.
140 */
141 public boolean classuse = false;
143 /**
144 * False if command line option "-notree" is used. Default value is true.
145 */
146 public boolean createtree = true;
148 /**
149 * True if command line option "-nodeprecated" is used. Default value is
150 * false.
151 */
152 public boolean nodeprecatedlist = false;
154 /**
155 * True if command line option "-nonavbar" is used. Default value is false.
156 */
157 public boolean nonavbar = false;
159 /**
160 * True if command line option "-nooverview" is used. Default value is
161 * false
162 */
163 private boolean nooverview = false;
165 /**
166 * True if command line option "-overview" is used. Default value is false.
167 */
168 public boolean overview = false;
170 /**
171 * This is true if option "-overview" is used or option "-overview" is not
172 * used and number of packages is more than one.
173 */
174 public boolean createoverview = false;
176 /**
177 * Collected set of doclint options
178 */
179 public Set<String> doclintOpts = new LinkedHashSet<String>();
181 /**
182 * Unique Resource Handler for this package.
183 */
184 public final MessageRetriever standardmessage;
186 /**
187 * First file to appear in the right-hand frame in the generated
188 * documentation.
189 */
190 public DocPath topFile = DocPath.empty;
192 /**
193 * The classdoc for the class file getting generated.
194 */
195 public ClassDoc currentcd = null; // Set this classdoc in the ClassWriter.
197 /**
198 * Constructor. Initializes resource for the
199 * {@link com.sun.tools.doclets.internal.toolkit.util.MessageRetriever MessageRetriever}.
200 */
201 public ConfigurationImpl() {
202 standardmessage = new MessageRetriever(this,
203 "com.sun.tools.doclets.formats.html.resources.standard");
204 }
206 /**
207 * Return the build date for the doclet.
208 */
209 @Override
210 public String getDocletSpecificBuildDate() {
211 return BUILD_DATE;
212 }
214 /**
215 * Depending upon the command line options provided by the user, set
216 * configure the output generation environment.
217 *
218 * @param options The array of option names and values.
219 */
220 @Override
221 public void setSpecificDocletOptions(String[][] options) {
222 for (int oi = 0; oi < options.length; ++oi) {
223 String[] os = options[oi];
224 String opt = os[0].toLowerCase();
225 if (opt.equals("-footer")) {
226 footer = os[1];
227 } else if (opt.equals("-header")) {
228 header = os[1];
229 } else if (opt.equals("-packagesheader")) {
230 packagesheader = os[1];
231 } else if (opt.equals("-doctitle")) {
232 doctitle = os[1];
233 } else if (opt.equals("-windowtitle")) {
234 windowtitle = os[1];
235 } else if (opt.equals("-top")) {
236 top = os[1];
237 } else if (opt.equals("-bottom")) {
238 bottom = os[1];
239 } else if (opt.equals("-helpfile")) {
240 helpfile = os[1];
241 } else if (opt.equals("-stylesheetfile")) {
242 stylesheetfile = os[1];
243 } else if (opt.equals("-charset")) {
244 charset = os[1];
245 } else if (opt.equals("-xdocrootparent")) {
246 docrootparent = os[1];
247 } else if (opt.equals("-nohelp")) {
248 nohelp = true;
249 } else if (opt.equals("-splitindex")) {
250 splitindex = true;
251 } else if (opt.equals("-noindex")) {
252 createindex = false;
253 } else if (opt.equals("-use")) {
254 classuse = true;
255 } else if (opt.equals("-notree")) {
256 createtree = false;
257 } else if (opt.equals("-nodeprecatedlist")) {
258 nodeprecatedlist = true;
259 } else if (opt.equals("-nonavbar")) {
260 nonavbar = true;
261 } else if (opt.equals("-nooverview")) {
262 nooverview = true;
263 } else if (opt.equals("-overview")) {
264 overview = true;
265 } else if (opt.equals("-xdoclint")) {
266 doclintOpts.add(null);
267 } else if (opt.startsWith("-xdoclint:")) {
268 doclintOpts.add(opt.substring(opt.indexOf(":") + 1));
269 }
270 }
271 if (root.specifiedClasses().length > 0) {
272 Map<String,PackageDoc> map = new HashMap<String,PackageDoc>();
273 PackageDoc pd;
274 ClassDoc[] classes = root.classes();
275 for (int i = 0; i < classes.length; i++) {
276 pd = classes[i].containingPackage();
277 if(! map.containsKey(pd.name())) {
278 map.put(pd.name(), pd);
279 }
280 }
281 }
282 setCreateOverview();
283 setTopFile(root);
285 if (root instanceof RootDocImpl) {
286 ((RootDocImpl) root).initDocLint(doclintOpts);
287 }
288 }
290 /**
291 * Returns the "length" of a given option. If an option takes no
292 * arguments, its length is one. If it takes one argument, it's
293 * length is two, and so on. This method is called by JavaDoc to
294 * parse the options it does not recognize. It then calls
295 * {@link #validOptions(String[][], DocErrorReporter)} to
296 * validate them.
297 * <b>Note:</b><br>
298 * The options arrive as case-sensitive strings. For options that
299 * are not case-sensitive, use toLowerCase() on the option string
300 * before comparing it.
301 * </blockquote>
302 *
303 * @return number of arguments + 1 for a option. Zero return means
304 * option not known. Negative value means error occurred.
305 */
306 public int optionLength(String option) {
307 int result = -1;
308 if ((result = super.optionLength(option)) > 0) {
309 return result;
310 }
311 // otherwise look for the options we have added
312 option = option.toLowerCase();
313 if (option.equals("-nodeprecatedlist") ||
314 option.equals("-noindex") ||
315 option.equals("-notree") ||
316 option.equals("-nohelp") ||
317 option.equals("-splitindex") ||
318 option.equals("-serialwarn") ||
319 option.equals("-use") ||
320 option.equals("-nonavbar") ||
321 option.equals("-nooverview") ||
322 option.equals("-xdoclint") ||
323 option.startsWith("-xdoclint:")) {
324 return 1;
325 } else if (option.equals("-help")) {
326 System.out.println(getText("doclet.usage"));
327 return 1;
328 } else if (option.equals("-footer") ||
329 option.equals("-header") ||
330 option.equals("-packagesheader") ||
331 option.equals("-doctitle") ||
332 option.equals("-windowtitle") ||
333 option.equals("-top") ||
334 option.equals("-bottom") ||
335 option.equals("-helpfile") ||
336 option.equals("-stylesheetfile") ||
337 option.equals("-charset") ||
338 option.equals("-overview") ||
339 option.equals("-xdocrootparent")) {
340 return 2;
341 } else {
342 return 0;
343 }
344 }
346 /**
347 * {@inheritDoc}
348 */
349 @Override
350 public boolean validOptions(String options[][],
351 DocErrorReporter reporter) {
352 boolean helpfile = false;
353 boolean nohelp = false;
354 boolean overview = false;
355 boolean nooverview = false;
356 boolean splitindex = false;
357 boolean noindex = false;
358 // check shared options
359 if (!generalValidOptions(options, reporter)) {
360 return false;
361 }
362 // otherwise look at our options
363 for (int oi = 0; oi < options.length; ++oi) {
364 String[] os = options[oi];
365 String opt = os[0].toLowerCase();
366 if (opt.equals("-helpfile")) {
367 if (nohelp == true) {
368 reporter.printError(getText("doclet.Option_conflict",
369 "-helpfile", "-nohelp"));
370 return false;
371 }
372 if (helpfile == true) {
373 reporter.printError(getText("doclet.Option_reuse",
374 "-helpfile"));
375 return false;
376 }
377 DocFile help = DocFile.createFileForInput(this, os[1]);
378 if (!help.exists()) {
379 reporter.printError(getText("doclet.File_not_found", os[1]));
380 return false;
381 }
382 helpfile = true;
383 } else if (opt.equals("-nohelp")) {
384 if (helpfile == true) {
385 reporter.printError(getText("doclet.Option_conflict",
386 "-nohelp", "-helpfile"));
387 return false;
388 }
389 nohelp = true;
390 } else if (opt.equals("-xdocrootparent")) {
391 try {
392 new URL(os[1]);
393 } catch (MalformedURLException e) {
394 reporter.printError(getText("doclet.MalformedURL", os[1]));
395 return false;
396 }
397 } else if (opt.equals("-overview")) {
398 if (nooverview == true) {
399 reporter.printError(getText("doclet.Option_conflict",
400 "-overview", "-nooverview"));
401 return false;
402 }
403 if (overview == true) {
404 reporter.printError(getText("doclet.Option_reuse",
405 "-overview"));
406 return false;
407 }
408 overview = true;
409 } else if (opt.equals("-nooverview")) {
410 if (overview == true) {
411 reporter.printError(getText("doclet.Option_conflict",
412 "-nooverview", "-overview"));
413 return false;
414 }
415 nooverview = true;
416 } else if (opt.equals("-splitindex")) {
417 if (noindex == true) {
418 reporter.printError(getText("doclet.Option_conflict",
419 "-splitindex", "-noindex"));
420 return false;
421 }
422 splitindex = true;
423 } else if (opt.equals("-noindex")) {
424 if (splitindex == true) {
425 reporter.printError(getText("doclet.Option_conflict",
426 "-noindex", "-splitindex"));
427 return false;
428 }
429 noindex = true;
430 } else if (opt.startsWith("-xdoclint:")) {
431 if (opt.contains("/")) {
432 reporter.printError(getText("doclet.Option_doclint_no_qualifiers"));
433 return false;
434 }
435 if (!DocLint.isValidOption(
436 opt.replace("-xdoclint:", DocLint.XMSGS_CUSTOM_PREFIX))) {
437 reporter.printError(getText("doclet.Option_doclint_invalid_arg"));
438 return false;
439 }
440 }
441 }
442 return true;
443 }
445 /**
446 * {@inheritDoc}
447 */
448 @Override
449 public MessageRetriever getDocletSpecificMsg() {
450 return standardmessage;
451 }
453 /**
454 * Decide the page which will appear first in the right-hand frame. It will
455 * be "overview-summary.html" if "-overview" option is used or no
456 * "-overview" but the number of packages is more than one. It will be
457 * "package-summary.html" of the respective package if there is only one
458 * package to document. It will be a class page(first in the sorted order),
459 * if only classes are provided on the command line.
460 *
461 * @param root Root of the program structure.
462 */
463 protected void setTopFile(RootDoc root) {
464 if (!checkForDeprecation(root)) {
465 return;
466 }
467 if (createoverview) {
468 topFile = DocPaths.OVERVIEW_SUMMARY;
469 } else {
470 if (packages.length == 1 && packages[0].name().equals("")) {
471 if (root.classes().length > 0) {
472 ClassDoc[] classarr = root.classes();
473 Arrays.sort(classarr);
474 ClassDoc cd = getValidClass(classarr);
475 topFile = DocPath.forClass(cd);
476 }
477 } else {
478 topFile = DocPath.forPackage(packages[0]).resolve(DocPaths.PACKAGE_SUMMARY);
479 }
480 }
481 }
483 protected ClassDoc getValidClass(ClassDoc[] classarr) {
484 if (!nodeprecated) {
485 return classarr[0];
486 }
487 for (int i = 0; i < classarr.length; i++) {
488 if (classarr[i].tags("deprecated").length == 0) {
489 return classarr[i];
490 }
491 }
492 return null;
493 }
495 protected boolean checkForDeprecation(RootDoc root) {
496 ClassDoc[] classarr = root.classes();
497 for (int i = 0; i < classarr.length; i++) {
498 if (isGeneratedDoc(classarr[i])) {
499 return true;
500 }
501 }
502 return false;
503 }
505 /**
506 * Generate "overview.html" page if option "-overview" is used or number of
507 * packages is more than one. Sets {@link #createoverview} field to true.
508 */
509 protected void setCreateOverview() {
510 if ((overview || packages.length > 1) && !nooverview) {
511 createoverview = true;
512 }
513 }
515 /**
516 * {@inheritDoc}
517 */
518 @Override
519 public WriterFactory getWriterFactory() {
520 return new WriterFactoryImpl(this);
521 }
523 /**
524 * {@inheritDoc}
525 */
526 @Override
527 public Comparator<ProgramElementDoc> getMemberComparator() {
528 return null;
529 }
531 /**
532 * {@inheritDoc}
533 */
534 @Override
535 public Locale getLocale() {
536 if (root instanceof RootDocImpl)
537 return ((RootDocImpl)root).getLocale();
538 else
539 return Locale.getDefault();
540 }
542 /**
543 * {@inheritDoc}
544 */
545 @Override
546 public JavaFileManager getFileManager() {
547 if (fileManager == null) {
548 if (root instanceof RootDocImpl)
549 fileManager = ((RootDocImpl) root).getFileManager();
550 else
551 fileManager = new JavacFileManager(new Context(), false, null);
552 }
553 return fileManager;
554 }
556 private JavaFileManager fileManager;
558 @Override
559 public boolean showMessage(SourcePosition pos, String key) {
560 if (root instanceof RootDocImpl) {
561 return pos == null || ((RootDocImpl) root).showTagMessages();
562 }
563 return true;
564 }
565 }