136 public final DocPath pathToRoot;
137
138 /**
139 * Platform-independent path from the current or the
140 * destination directory to the file getting generated.
141 * Used when creating the file.
142 */
143 public final DocPath path;
144
145 /**
146 * Name of the file getting generated. If the file getting generated is
147 * "java/lang/Object.html", then the filename is "Object.html".
148 */
149 public final DocPath filename;
150
151 /**
152 * The global configuration information for this run.
153 */
154 public final HtmlConfiguration configuration;
155
156 protected final Utils utils;
157
158 protected final Contents contents;
159
160 protected final Messages messages;
161
162 protected final Resources resources;
163
164 protected final Links links;
165
166 protected final DocPaths docPaths;
167
168 /**
169 * To check whether annotation heading is printed or not.
170 */
171 protected boolean printedAnnotationHeading = false;
172
173 /**
174 * To check whether annotation field heading is printed or not.
175 */
191 protected String winTitle;
192
193 protected Script mainBodyScript;
194
195 /**
196 * A table of the anchors used for at-index and related tags,
197 * so that they can be made unique by appending a suitable suffix.
198 * (Ideally, javadoc should be tracking all id's generated in a file
199 * to avoid generating duplicates.)
200 */
201 Map<String, Integer> indexAnchorTable = new HashMap<>();
202
203 /**
204 * Constructor to construct the HtmlStandardWriter object.
205 *
206 * @param configuration the configuration for this doclet
207 * @param path the file to be generated.
208 */
209 public HtmlDocletWriter(HtmlConfiguration configuration, DocPath path) {
210 this.configuration = configuration;
211 this.contents = configuration.contents;
212 this.messages = configuration.messages;
213 this.resources = configuration.resources;
214 this.links = new Links(path);
215 this.utils = configuration.utils;
216 this.path = path;
217 this.pathToRoot = path.parent().invert();
218 this.filename = path.basename();
219 this.docPaths = configuration.docPaths;
220 this.mainBodyScript = new Script();
221
222 messages.notice("doclet.Generating_0",
223 DocFile.createFileForOutput(configuration, path).getPath());
224 }
225
226 /**
227 * Replace {@docRoot} tag used in options that accept HTML text, such
228 * as -header, -footer, -top and -bottom, and when converting a relative
229 * HREF where commentTagsToString inserts a {@docRoot} where one was
230 * missing. (Also see DocRootTaglet for {@docRoot} tags in doc
242 * Note: This doc comment was written with '&#064;' representing '@'
243 * to prevent the inline tag from being interpreted.
244 */
245 public String replaceDocRootDir(String htmlstr) {
246 // Return if no inline tags exist
247 int index = htmlstr.indexOf("{@");
248 if (index < 0) {
249 return htmlstr;
250 }
251 Matcher docrootMatcher = docrootPattern.matcher(htmlstr);
252 if (!docrootMatcher.find()) {
253 return htmlstr;
254 }
255 StringBuilder buf = new StringBuilder();
256 int prevEnd = 0;
257 do {
258 int match = docrootMatcher.start();
259 // append htmlstr up to start of next {@docroot}
260 buf.append(htmlstr.substring(prevEnd, match));
261 prevEnd = docrootMatcher.end();
262 if (configuration.docrootparent.length() > 0 && htmlstr.startsWith("/..", prevEnd)) {
263 // Insert the absolute link if {@docRoot} is followed by "/..".
264 buf.append(configuration.docrootparent);
265 prevEnd += 3;
266 } else {
267 // Insert relative path where {@docRoot} was located
268 buf.append(pathToRoot.isEmpty() ? "." : pathToRoot.getPath());
269 }
270 // Append slash if next character is not a slash
271 if (prevEnd < htmlstr.length() && htmlstr.charAt(prevEnd) != '/') {
272 buf.append('/');
273 }
274 } while (docrootMatcher.find());
275 buf.append(htmlstr.substring(prevEnd));
276 return buf.toString();
277 }
278 //where:
279 // Note: {@docRoot} is not case sensitive when passed in w/command line option:
280 private static final Pattern docrootPattern =
281 Pattern.compile(Pattern.quote("{@docroot}"), Pattern.CASE_INSENSITIVE);
282
283 /**
284 * Get the script to show or hide the All classes link.
322 if ((!intfacs.isEmpty()
323 && vmt.getImplementedMethods(method).isEmpty() == false)
324 || overriddenMethod != null) {
325 MethodWriterImpl.addImplementsInfo(this, method, dl);
326 if (overriddenMethod != null) {
327 MethodWriterImpl.addOverridden(this,
328 utils.overriddenType(method),
329 overriddenMethod,
330 dl);
331 }
332 }
333 }
334
335 /**
336 * Adds the tags information.
337 *
338 * @param e the Element for which the tags will be generated
339 * @param htmltree the documentation tree to which the tags will be added
340 */
341 protected void addTagsInfo(Element e, Content htmltree) {
342 if (configuration.nocomment) {
343 return;
344 }
345 Content dl = new HtmlTree(HtmlTag.DL);
346 if (utils.isExecutableElement(e) && !utils.isConstructor(e)) {
347 addMethodInfo((ExecutableElement)e, dl);
348 }
349 Content output = new ContentBuilder();
350 TagletWriter.genTagOutput(configuration.tagletManager, e,
351 configuration.tagletManager.getBlockTaglets(e),
352 getTagletWriterInstance(false), output);
353 dl.add(output);
354 htmltree.add(dl);
355 }
356
357 /**
358 * Check whether there are any tags for Serialization Overview
359 * section to be printed.
360 *
361 * @param field the VariableElement object to check for tags.
362 * @return true if there are tags to be printed else return false.
431 *
432 * @param metakeywords Array of String keywords for META tag. Each element
433 * of the array is assigned to a separate META tag.
434 * Pass in null for no array
435 * @param description the content for the description META tag.
436 * @param extraHeadContent any additional content to be included in the HEAD element
437 * @param localStylesheets local stylesheets to be included in the HEAD element
438 * @param body the body htmltree to be included in the document
439 * @throws DocFileIOException if there is a problem writing the file
440 */
441 public void printHtmlDocument(List<String> metakeywords,
442 String description,
443 Content extraHeadContent,
444 List<DocPath> localStylesheets,
445 Content body)
446 throws DocFileIOException {
447 Content htmlComment = contents.newPage;
448 List<DocPath> additionalStylesheets = configuration.getAdditionalStylesheets();
449 additionalStylesheets.addAll(localStylesheets);
450 Head head = new Head(path, configuration.docletVersion, configuration.startTime)
451 .setTimestamp(!configuration.notimestamp)
452 .setDescription(description)
453 .setGenerator(getGenerator(getClass()))
454 .setTitle(winTitle)
455 .setCharset(configuration.charset)
456 .addKeywords(metakeywords)
457 .setStylesheets(configuration.getMainStylesheet(), additionalStylesheets)
458 .setIndex(configuration.createindex, mainBodyScript)
459 .addContent(extraHeadContent);
460
461 Content htmlTree = HtmlTree.HTML(configuration.getLocale().getLanguage(), head.toContent(), body);
462 HtmlDocument htmlDocument = new HtmlDocument(htmlComment, htmlTree);
463 htmlDocument.write(DocFile.createFileForOutput(configuration, path));
464 }
465
466 /**
467 * Get the window title.
468 *
469 * @param title the title string to construct the complete window title
470 * @return the window title string
471 */
472 public String getWindowTitle(String title) {
473 if (configuration.windowtitle.length() > 0) {
474 title += " (" + configuration.windowtitle + ")";
475 }
476 return title;
477 }
478
479 /**
480 * Get user specified header and the footer.
481 *
482 * @param header if true print the user provided header else print the
483 * user provided footer.
484 */
485 public Content getUserHeaderFooter(boolean header) {
486 String content;
487 if (header) {
488 content = replaceDocRootDir(configuration.header);
489 } else {
490 if (configuration.footer.length() != 0) {
491 content = replaceDocRootDir(configuration.footer);
492 } else {
493 content = replaceDocRootDir(configuration.header);
494 }
495 }
496 Content rawContent = new RawHtml(content);
497 return rawContent;
498 }
499
500 /**
501 * Adds the user specified top.
502 *
503 * @param htmlTree the content tree to which user specified top will be added
504 */
505 public void addTop(Content htmlTree) {
506 Content top = new RawHtml(replaceDocRootDir(configuration.top));
507 htmlTree.add(top);
508 }
509
510 /**
511 * Adds the user specified bottom.
512 *
513 * @param htmlTree the content tree to which user specified bottom will be added
514 */
515 public void addBottom(Content htmlTree) {
516 Content bottom = new RawHtml(replaceDocRootDir(configuration.bottom));
517 Content small = HtmlTree.SMALL(bottom);
518 Content p = HtmlTree.P(HtmlStyle.legalCopy, small);
519 htmlTree.add(p);
520 }
521
522 /**
523 * Get the overview tree link for the main tree.
524 *
525 * @param label the label for the link
526 * @return a content tree for the link
527 */
528 protected Content getNavLinkMainTree(String label) {
529 Content mainTreeContent = links.createLink(pathToRoot.resolve(DocPaths.OVERVIEW_TREE),
530 new StringContent(label));
531 Content li = HtmlTree.LI(mainTreeContent);
532 return li;
533 }
534
535 /**
536 * Get table caption.
1233 * @param htmltree the documentation tree to which the comment tags will be added
1234 */
1235 private void addCommentTags(Element element, List<? extends DocTree> tags, boolean depr,
1236 boolean first, boolean inSummary, Content htmltree) {
1237 addCommentTags(element, null, tags, depr, first, inSummary, htmltree);
1238 }
1239
1240 /**
1241 * Adds the comment tags.
1242 *
1243 * @param element for which the comment tags will be generated
1244 * @param holderTag the block tag context for the inline tags
1245 * @param tags the first sentence tags for the doc
1246 * @param depr true if it is deprecated
1247 * @param first true if the first sentence tags should be added
1248 * @param inSummary true if the comment tags are added into the summary section
1249 * @param htmltree the documentation tree to which the comment tags will be added
1250 */
1251 private void addCommentTags(Element element, DocTree holderTag, List<? extends DocTree> tags, boolean depr,
1252 boolean first, boolean inSummary, Content htmltree) {
1253 if(configuration.nocomment){
1254 return;
1255 }
1256 Content div;
1257 Content result = commentTagsToContent(null, element, tags, first, inSummary);
1258 if (depr) {
1259 div = HtmlTree.DIV(HtmlStyle.deprecationComment, result);
1260 htmltree.add(div);
1261 }
1262 else {
1263 div = HtmlTree.DIV(HtmlStyle.block, result);
1264 htmltree.add(div);
1265 }
1266 if (tags.isEmpty()) {
1267 htmltree.add(Entity.NO_BREAK_SPACE);
1268 }
1269 }
1270
1271 boolean ignoreNonInlineTag(DocTree dtree) {
1272 Name name = null;
1273 if (dtree.getKind() == Kind.START_ELEMENT) {
1394 String quote;
1395 switch (node.getValueKind()) {
1396 case DOUBLE:
1397 quote = "\"";
1398 break;
1399 case SINGLE:
1400 quote = "\'";
1401 break;
1402 default:
1403 quote = "";
1404 break;
1405 }
1406 sb.append(quote);
1407 result.add(sb);
1408 Content docRootContent = new ContentBuilder();
1409
1410 boolean isHRef = inAnAtag() && node.getName().toString().equalsIgnoreCase("href");
1411 for (DocTree dt : node.getValue()) {
1412 if (utils.isText(dt) && isHRef) {
1413 String text = ((TextTree) dt).getBody();
1414 if (text.startsWith("/..") && !configuration.docrootparent.isEmpty()) {
1415 result.add(configuration.docrootparent);
1416 docRootContent = new ContentBuilder();
1417 result.add(textCleanup(text.substring(3), isLastNode));
1418 } else {
1419 if (!docRootContent.isEmpty()) {
1420 docRootContent = copyDocRootContent(docRootContent);
1421 } else {
1422 text = redirectRelativeLinks(element, (TextTree) dt);
1423 }
1424 result.add(textCleanup(text, isLastNode));
1425 }
1426 } else {
1427 docRootContent = copyDocRootContent(docRootContent);
1428 dt.accept(this, docRootContent);
1429 }
1430 }
1431 copyDocRootContent(docRootContent);
1432 result.add(quote);
1433 return false;
1434 }
1435
|
136 public final DocPath pathToRoot;
137
138 /**
139 * Platform-independent path from the current or the
140 * destination directory to the file getting generated.
141 * Used when creating the file.
142 */
143 public final DocPath path;
144
145 /**
146 * Name of the file getting generated. If the file getting generated is
147 * "java/lang/Object.html", then the filename is "Object.html".
148 */
149 public final DocPath filename;
150
151 /**
152 * The global configuration information for this run.
153 */
154 public final HtmlConfiguration configuration;
155
156 protected final HtmlOptions options;
157
158 protected final Utils utils;
159
160 protected final Contents contents;
161
162 protected final Messages messages;
163
164 protected final Resources resources;
165
166 protected final Links links;
167
168 protected final DocPaths docPaths;
169
170 /**
171 * To check whether annotation heading is printed or not.
172 */
173 protected boolean printedAnnotationHeading = false;
174
175 /**
176 * To check whether annotation field heading is printed or not.
177 */
193 protected String winTitle;
194
195 protected Script mainBodyScript;
196
197 /**
198 * A table of the anchors used for at-index and related tags,
199 * so that they can be made unique by appending a suitable suffix.
200 * (Ideally, javadoc should be tracking all id's generated in a file
201 * to avoid generating duplicates.)
202 */
203 Map<String, Integer> indexAnchorTable = new HashMap<>();
204
205 /**
206 * Constructor to construct the HtmlStandardWriter object.
207 *
208 * @param configuration the configuration for this doclet
209 * @param path the file to be generated.
210 */
211 public HtmlDocletWriter(HtmlConfiguration configuration, DocPath path) {
212 this.configuration = configuration;
213 this.options = configuration.getOptions();
214 this.contents = configuration.contents;
215 this.messages = configuration.messages;
216 this.resources = configuration.resources;
217 this.links = new Links(path);
218 this.utils = configuration.utils;
219 this.path = path;
220 this.pathToRoot = path.parent().invert();
221 this.filename = path.basename();
222 this.docPaths = configuration.docPaths;
223 this.mainBodyScript = new Script();
224
225 messages.notice("doclet.Generating_0",
226 DocFile.createFileForOutput(configuration, path).getPath());
227 }
228
229 /**
230 * Replace {@docRoot} tag used in options that accept HTML text, such
231 * as -header, -footer, -top and -bottom, and when converting a relative
232 * HREF where commentTagsToString inserts a {@docRoot} where one was
233 * missing. (Also see DocRootTaglet for {@docRoot} tags in doc
245 * Note: This doc comment was written with '&#064;' representing '@'
246 * to prevent the inline tag from being interpreted.
247 */
248 public String replaceDocRootDir(String htmlstr) {
249 // Return if no inline tags exist
250 int index = htmlstr.indexOf("{@");
251 if (index < 0) {
252 return htmlstr;
253 }
254 Matcher docrootMatcher = docrootPattern.matcher(htmlstr);
255 if (!docrootMatcher.find()) {
256 return htmlstr;
257 }
258 StringBuilder buf = new StringBuilder();
259 int prevEnd = 0;
260 do {
261 int match = docrootMatcher.start();
262 // append htmlstr up to start of next {@docroot}
263 buf.append(htmlstr.substring(prevEnd, match));
264 prevEnd = docrootMatcher.end();
265 if (options.docrootParent.length() > 0 && htmlstr.startsWith("/..", prevEnd)) {
266 // Insert the absolute link if {@docRoot} is followed by "/..".
267 buf.append(options.docrootParent);
268 prevEnd += 3;
269 } else {
270 // Insert relative path where {@docRoot} was located
271 buf.append(pathToRoot.isEmpty() ? "." : pathToRoot.getPath());
272 }
273 // Append slash if next character is not a slash
274 if (prevEnd < htmlstr.length() && htmlstr.charAt(prevEnd) != '/') {
275 buf.append('/');
276 }
277 } while (docrootMatcher.find());
278 buf.append(htmlstr.substring(prevEnd));
279 return buf.toString();
280 }
281 //where:
282 // Note: {@docRoot} is not case sensitive when passed in w/command line option:
283 private static final Pattern docrootPattern =
284 Pattern.compile(Pattern.quote("{@docroot}"), Pattern.CASE_INSENSITIVE);
285
286 /**
287 * Get the script to show or hide the All classes link.
325 if ((!intfacs.isEmpty()
326 && vmt.getImplementedMethods(method).isEmpty() == false)
327 || overriddenMethod != null) {
328 MethodWriterImpl.addImplementsInfo(this, method, dl);
329 if (overriddenMethod != null) {
330 MethodWriterImpl.addOverridden(this,
331 utils.overriddenType(method),
332 overriddenMethod,
333 dl);
334 }
335 }
336 }
337
338 /**
339 * Adds the tags information.
340 *
341 * @param e the Element for which the tags will be generated
342 * @param htmltree the documentation tree to which the tags will be added
343 */
344 protected void addTagsInfo(Element e, Content htmltree) {
345 if (options.noComment) {
346 return;
347 }
348 Content dl = new HtmlTree(HtmlTag.DL);
349 if (utils.isExecutableElement(e) && !utils.isConstructor(e)) {
350 addMethodInfo((ExecutableElement)e, dl);
351 }
352 Content output = new ContentBuilder();
353 TagletWriter.genTagOutput(configuration.tagletManager, e,
354 configuration.tagletManager.getBlockTaglets(e),
355 getTagletWriterInstance(false), output);
356 dl.add(output);
357 htmltree.add(dl);
358 }
359
360 /**
361 * Check whether there are any tags for Serialization Overview
362 * section to be printed.
363 *
364 * @param field the VariableElement object to check for tags.
365 * @return true if there are tags to be printed else return false.
434 *
435 * @param metakeywords Array of String keywords for META tag. Each element
436 * of the array is assigned to a separate META tag.
437 * Pass in null for no array
438 * @param description the content for the description META tag.
439 * @param extraHeadContent any additional content to be included in the HEAD element
440 * @param localStylesheets local stylesheets to be included in the HEAD element
441 * @param body the body htmltree to be included in the document
442 * @throws DocFileIOException if there is a problem writing the file
443 */
444 public void printHtmlDocument(List<String> metakeywords,
445 String description,
446 Content extraHeadContent,
447 List<DocPath> localStylesheets,
448 Content body)
449 throws DocFileIOException {
450 Content htmlComment = contents.newPage;
451 List<DocPath> additionalStylesheets = configuration.getAdditionalStylesheets();
452 additionalStylesheets.addAll(localStylesheets);
453 Head head = new Head(path, configuration.docletVersion, configuration.startTime)
454 .setTimestamp(!options.noTimestamp)
455 .setDescription(description)
456 .setGenerator(getGenerator(getClass()))
457 .setTitle(winTitle)
458 .setCharset(options.charset)
459 .addKeywords(metakeywords)
460 .setStylesheets(configuration.getMainStylesheet(), additionalStylesheets)
461 .setIndex(options.createIndex, mainBodyScript)
462 .addContent(extraHeadContent);
463
464 Content htmlTree = HtmlTree.HTML(configuration.getLocale().getLanguage(), head.toContent(), body);
465 HtmlDocument htmlDocument = new HtmlDocument(htmlComment, htmlTree);
466 htmlDocument.write(DocFile.createFileForOutput(configuration, path));
467 }
468
469 /**
470 * Get the window title.
471 *
472 * @param title the title string to construct the complete window title
473 * @return the window title string
474 */
475 public String getWindowTitle(String title) {
476 if (options.windowTitle.length() > 0) {
477 title += " (" + options.windowTitle + ")";
478 }
479 return title;
480 }
481
482 /**
483 * Get user specified header and the footer.
484 *
485 * @param header if true print the user provided header else print the
486 * user provided footer.
487 */
488 public Content getUserHeaderFooter(boolean header) {
489 String content;
490 if (header) {
491 content = replaceDocRootDir(options.header);
492 } else {
493 if (options.footer.length() != 0) {
494 content = replaceDocRootDir(options.footer);
495 } else {
496 content = replaceDocRootDir(options.header);
497 }
498 }
499 Content rawContent = new RawHtml(content);
500 return rawContent;
501 }
502
503 /**
504 * Adds the user specified top.
505 *
506 * @param htmlTree the content tree to which user specified top will be added
507 */
508 public void addTop(Content htmlTree) {
509 Content top = new RawHtml(replaceDocRootDir(options.top));
510 htmlTree.add(top);
511 }
512
513 /**
514 * Adds the user specified bottom.
515 *
516 * @param htmlTree the content tree to which user specified bottom will be added
517 */
518 public void addBottom(Content htmlTree) {
519 Content bottom = new RawHtml(replaceDocRootDir(options.bottom));
520 Content small = HtmlTree.SMALL(bottom);
521 Content p = HtmlTree.P(HtmlStyle.legalCopy, small);
522 htmlTree.add(p);
523 }
524
525 /**
526 * Get the overview tree link for the main tree.
527 *
528 * @param label the label for the link
529 * @return a content tree for the link
530 */
531 protected Content getNavLinkMainTree(String label) {
532 Content mainTreeContent = links.createLink(pathToRoot.resolve(DocPaths.OVERVIEW_TREE),
533 new StringContent(label));
534 Content li = HtmlTree.LI(mainTreeContent);
535 return li;
536 }
537
538 /**
539 * Get table caption.
1236 * @param htmltree the documentation tree to which the comment tags will be added
1237 */
1238 private void addCommentTags(Element element, List<? extends DocTree> tags, boolean depr,
1239 boolean first, boolean inSummary, Content htmltree) {
1240 addCommentTags(element, null, tags, depr, first, inSummary, htmltree);
1241 }
1242
1243 /**
1244 * Adds the comment tags.
1245 *
1246 * @param element for which the comment tags will be generated
1247 * @param holderTag the block tag context for the inline tags
1248 * @param tags the first sentence tags for the doc
1249 * @param depr true if it is deprecated
1250 * @param first true if the first sentence tags should be added
1251 * @param inSummary true if the comment tags are added into the summary section
1252 * @param htmltree the documentation tree to which the comment tags will be added
1253 */
1254 private void addCommentTags(Element element, DocTree holderTag, List<? extends DocTree> tags, boolean depr,
1255 boolean first, boolean inSummary, Content htmltree) {
1256 if (options.noComment){
1257 return;
1258 }
1259 Content div;
1260 Content result = commentTagsToContent(null, element, tags, first, inSummary);
1261 if (depr) {
1262 div = HtmlTree.DIV(HtmlStyle.deprecationComment, result);
1263 htmltree.add(div);
1264 }
1265 else {
1266 div = HtmlTree.DIV(HtmlStyle.block, result);
1267 htmltree.add(div);
1268 }
1269 if (tags.isEmpty()) {
1270 htmltree.add(Entity.NO_BREAK_SPACE);
1271 }
1272 }
1273
1274 boolean ignoreNonInlineTag(DocTree dtree) {
1275 Name name = null;
1276 if (dtree.getKind() == Kind.START_ELEMENT) {
1397 String quote;
1398 switch (node.getValueKind()) {
1399 case DOUBLE:
1400 quote = "\"";
1401 break;
1402 case SINGLE:
1403 quote = "\'";
1404 break;
1405 default:
1406 quote = "";
1407 break;
1408 }
1409 sb.append(quote);
1410 result.add(sb);
1411 Content docRootContent = new ContentBuilder();
1412
1413 boolean isHRef = inAnAtag() && node.getName().toString().equalsIgnoreCase("href");
1414 for (DocTree dt : node.getValue()) {
1415 if (utils.isText(dt) && isHRef) {
1416 String text = ((TextTree) dt).getBody();
1417 if (text.startsWith("/..") && !options.docrootParent.isEmpty()) {
1418 result.add(options.docrootParent);
1419 docRootContent = new ContentBuilder();
1420 result.add(textCleanup(text.substring(3), isLastNode));
1421 } else {
1422 if (!docRootContent.isEmpty()) {
1423 docRootContent = copyDocRootContent(docRootContent);
1424 } else {
1425 text = redirectRelativeLinks(element, (TextTree) dt);
1426 }
1427 result.add(textCleanup(text, isLastNode));
1428 }
1429 } else {
1430 docRootContent = copyDocRootContent(docRootContent);
1431 dt.accept(this, docRootContent);
1432 }
1433 }
1434 copyDocRootContent(docRootContent);
1435 result.add(quote);
1436 return false;
1437 }
1438
|