< prev index next >

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AbstractMemberWriter.java

Print this page




  29 import java.util.List;
  30 import java.util.Set;
  31 import java.util.TreeSet;
  32 import java.util.stream.Collectors;
  33 
  34 import javax.lang.model.element.Element;
  35 import javax.lang.model.element.ExecutableElement;
  36 import javax.lang.model.element.Modifier;
  37 import javax.lang.model.element.TypeElement;
  38 import javax.lang.model.element.TypeParameterElement;
  39 import javax.lang.model.type.TypeMirror;
  40 
  41 import com.sun.source.doctree.DocTree;
  42 
  43 import jdk.javadoc.internal.doclets.formats.html.markup.ContentBuilder;
  44 import jdk.javadoc.internal.doclets.formats.html.markup.Entity;
  45 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle;
  46 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTag;
  47 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;
  48 import jdk.javadoc.internal.doclets.formats.html.markup.Links;
  49 import jdk.javadoc.internal.doclets.formats.html.markup.StringContent;
  50 import jdk.javadoc.internal.doclets.formats.html.markup.Table;
  51 import jdk.javadoc.internal.doclets.formats.html.markup.TableHeader;
  52 import jdk.javadoc.internal.doclets.toolkit.Content;
  53 import jdk.javadoc.internal.doclets.toolkit.MemberSummaryWriter;
  54 import jdk.javadoc.internal.doclets.toolkit.Resources;
  55 import jdk.javadoc.internal.doclets.toolkit.taglets.DeprecatedTaglet;
  56 import jdk.javadoc.internal.doclets.toolkit.util.DocletConstants;
  57 import jdk.javadoc.internal.doclets.toolkit.util.Utils;
  58 
  59 import static javax.lang.model.element.Modifier.ABSTRACT;
  60 import static javax.lang.model.element.Modifier.NATIVE;
  61 import static javax.lang.model.element.Modifier.PUBLIC;
  62 import static javax.lang.model.element.Modifier.STRICTFP;
  63 import static javax.lang.model.element.Modifier.SYNCHRONIZED;
  64 
  65 /**
  66  * The base class for member writers.
  67  *
  68  *  <p><b>This is NOT part of any supported API.
  69  *  If you write code that depends on this, you do so at your own risk.
  70  *  This code and its internal interfaces are subject to change or
  71  *  deletion without notice.</b>
  72  *
  73  * @author Robert Field
  74  * @author Atul M Dambalkar
  75  * @author Jamie Ho (Re-write)
  76  * @author Bhavesh Patel (Modified)


 204             TypeElement typeElement, Element member, Content tdSummary);
 205 
 206     /**
 207      * Add the inherited summary link for the member.
 208      *
 209      * @param typeElement the TypeElement to be documented
 210      * @param member the member to be documented
 211      * @param linksTree the content tree to which the inherited summary link will be added
 212      */
 213     protected abstract void addInheritedSummaryLink(TypeElement typeElement,
 214             Element member, Content linksTree);
 215 
 216     /**
 217      * Get the deprecated link.
 218      *
 219      * @param member the member being linked to
 220      * @return a content tree representing the link
 221      */
 222     protected abstract Content getDeprecatedLink(Element member);
 223 

















































 224     protected CharSequence makeSpace(int len) {
 225         if (len <= 0) {
 226             return "";
 227         }
 228         StringBuilder sb = new StringBuilder(len);
 229         for (int i = 0; i < len; i++) {
 230             sb.append(' ');
 231         }
 232         return sb;
 233     }
 234 
 235     /**
 236      * Add the modifier and type for the member in the member summary.
 237      *
 238      * @param member the member to add the type for
 239      * @param type the type to add
 240      * @param tdSummaryType the content tree to which the modified and type will be added
 241      */
 242     protected void addModifierAndType(Element member, TypeMirror type,
 243             Content tdSummaryType) {


 487         }
 488         Table table = getSummaryTable();
 489         if (table.needsScript()) {
 490             writer.getMainBodyScript().append(table.getScript());
 491         }
 492         return table.toContent();
 493     }
 494 
 495     /**
 496      * Get the member tree to be documented.
 497      *
 498      * @param memberTree the content tree of member to be documented
 499      * @return a content tree that will be added to the class documentation
 500      */
 501     @Override
 502     public Content getMemberTree(Content memberTree) {
 503         return writer.getMemberTree(memberTree);
 504     }
 505 
 506     /**
 507      * A content builder for member signatures.




 508      */
 509     class MemberSignature {
 510 
 511         private Element element;
 512         private Content typeParameters;
 513         private Content returnType;
 514         private Content parameters;
 515         private Content exceptions;
 516 
 517         // Threshold for length of type parameters before switching from inline to block representation.
 518         private final static int TYPE_PARAMS_MAX_INLINE_LENGTH = 50;
 519 
 520         // Threshold for combined length of modifiers, type params and return type before breaking
 521         // it up with a line break before the return type.
 522         private final static int RETURN_TYPE_MAX_LINE_LENGTH = 50;
 523 
 524         /**
 525          * Create a new member signature builder.
 526          *
 527          * @param element The element for which to create a signature.
 528          */
 529         MemberSignature(Element element) {
 530             this.element = element;
 531         }
 532 
 533         /**
 534          * Add the type parameters for an executable member.
 535          *
 536          * @param typeParameters the content tree containing the type parameters to add.
 537          * @return this MemberSignature instance
 538          */
 539         MemberSignature addTypeParameters(Content typeParameters) {
 540             this.typeParameters = typeParameters;
 541             return this;
 542         }
 543 
 544         /**
 545          * Add the return type for an executable member.
 546          *
 547          * @param returnType the content tree containing the return type to add.
 548          * @return this MemberSignature instance
 549          */
 550         MemberSignature addReturnType(Content returnType) {
 551             this.returnType = returnType;
 552             return this;
 553         }
 554 
 555         /**
 556          * Add the type information for a non-executable member.
 557          *
 558          * @param type the type of the member.
 559          * @return this MemberSignature instance
 560          */
 561         MemberSignature addType(TypeMirror type) {
 562             this.returnType = writer.getLink(new LinkInfoImpl(configuration, LinkInfoImpl.Kind.MEMBER, type));
 563             return this;
 564         }
 565 
 566         /**
 567          * Add the parameter information of an executable member.
 568          *
 569          * @param paramTree the content tree containing the parameter information.
 570          * @return this MemberSignature instance
 571          */
 572         MemberSignature addParameters(Content paramTree) {
 573             this.parameters = paramTree;
 574             return this;
 575         }
 576 
 577         /**
 578          * Add the exception information of an executable member.
 579          *
 580          * @param exceptionTree the content tree containing the exception information
 581          * @return this MemberSignature instance
 582          */
 583         MemberSignature addExceptions(Content exceptionTree) {
 584             this.exceptions = exceptionTree;
 585             return this;
 586         }
 587 
 588         /**
 589          * Return a HTML tree containing the member signature.
 590          *
 591          * @return a HTML tree containing the member signature
 592          */
 593         Content toContent() {
 594             Content content = new ContentBuilder();
 595             // Position of last line separator.
 596             int lastLineSeparator = 0;
 597 
 598             // Annotations
 599             Content annotationInfo = writer.getAnnotationInfo(element.getAnnotationMirrors(), true);
 600             if (!annotationInfo.isEmpty()) {
 601                 content.add(HtmlTree.SPAN(HtmlStyle.annotations, annotationInfo));
 602                 lastLineSeparator = content.charCount();
 603             }
 604 
 605             // Modifiers
 606             appendModifiers(content);
 607 
 608             // Type parameters
 609             if (typeParameters != null && !typeParameters.isEmpty()) {
 610                 lastLineSeparator = appendTypeParameters(content, lastLineSeparator);
 611             }
 612 
 613             // Return type
 614             if (returnType != null) {
 615                 content.add(HtmlTree.SPAN(HtmlStyle.returnType, returnType));
 616                 content.add(Entity.NO_BREAK_SPACE);
 617             }
 618 
 619             // Name
 620             HtmlTree nameSpan = new HtmlTree(HtmlTag.SPAN);
 621             nameSpan.setStyle(HtmlStyle.memberName);
 622             if (configuration.linksource) {
 623                 Content name = new StringContent(name(element));
 624                 writer.addSrcLink(element, name, nameSpan);
 625             } else {
 626                 nameSpan.add(name(element));
 627             }
 628             content.add(nameSpan);
 629 
 630 
 631             // Parameters and exceptions
 632             if (parameters != null) {
 633                 appendParametersAndExceptions(content, lastLineSeparator);
 634             }
 635 
 636             return HtmlTree.DIV(HtmlStyle.memberSignature, content);
 637         }
 638 
 639         /**
 640          * Add the modifier for the member. The modifiers are ordered as specified
 641          * by <em>The Java Language Specification</em>.
 642          *
 643          * @param htmltree the content tree to which the modifier information will be added.
 644          */
 645         private void appendModifiers(Content htmltree) {
 646             Set<Modifier> set = new TreeSet<>(element.getModifiers());
 647 
 648             // remove the ones we really don't need
 649             set.remove(NATIVE);
 650             set.remove(SYNCHRONIZED);
 651             set.remove(STRICTFP);
 652 
 653             // According to JLS, we should not be showing public modifier for
 654             // interface methods.
 655             if ((utils.isField(element) || utils.isMethod(element))
 656                     && ((writer instanceof ClassWriterImpl
 657                     && utils.isInterface(((ClassWriterImpl) writer).getTypeElement())  ||
 658                     writer instanceof AnnotationTypeWriterImpl) )) {
 659                 // Remove the implicit abstract and public modifiers
 660                 if (utils.isMethod(element) &&
 661                         (utils.isInterface(element.getEnclosingElement()) ||
 662                                 utils.isAnnotationType(element.getEnclosingElement()))) {
 663                     set.remove(ABSTRACT);
 664                     set.remove(PUBLIC);
 665                 }
 666                 if (!utils.isMethod(element)) {
 667                     set.remove(PUBLIC);
 668                 }
 669             }
 670             if (!set.isEmpty()) {
 671                 String mods = set.stream().map(Modifier::toString).collect(Collectors.joining(" "));
 672                 htmltree.add(HtmlTree.SPAN(HtmlStyle.modifiers, new StringContent(mods)));
 673                 htmltree.add(Entity.NO_BREAK_SPACE);
 674             }
 675         }
 676 
 677         /**
 678          * Append the type parameter information to the HTML tree.
 679          *
 680          * @param htmltree the HTML tree
 681          * @param lastLineSeparator index of last line separator in HTML tree
 682          * @return the new index of the last line separator
 683          */
 684         private int appendTypeParameters(Content htmltree, int lastLineSeparator) {
 685             // Apply different wrapping strategies for type parameters
 686             // depending of combined length of type parameters and return type.
 687             int typeParamLength = typeParameters.charCount();
 688 
 689             if (typeParamLength >= TYPE_PARAMS_MAX_INLINE_LENGTH) {
 690                 htmltree.add(HtmlTree.SPAN(HtmlStyle.typeParametersLong, typeParameters));
 691             } else {
 692                 htmltree.add(HtmlTree.SPAN(HtmlStyle.typeParameters, typeParameters));
 693             }
 694 
 695             int lineLength = htmltree.charCount() - lastLineSeparator;
 696             int newLastLineSeparator = lastLineSeparator;
 697 
 698             // sum below includes length of modifiers plus type params added above
 699             if (lineLength + returnType.charCount()> RETURN_TYPE_MAX_LINE_LENGTH) {
 700                 htmltree.add(DocletConstants.NL);
 701                 newLastLineSeparator = htmltree.charCount();
 702             } else {
 703                 htmltree.add(Entity.NO_BREAK_SPACE);
 704             }
 705 
 706             return newLastLineSeparator;
 707         }
 708 
 709         /**
 710          * Append the parameters and exceptions information to the HTML tree.
 711          *
 712          * @param htmltree the HTML tree
 713          * @param lastLineSeparator the index of the last line separator in HTML tree
 714          */
 715         private void appendParametersAndExceptions(Content htmltree, int lastLineSeparator) {
 716             // Record current position for indentation of exceptions
 717             int indentSize = htmltree.charCount() - lastLineSeparator;
 718 
 719             if (parameters.isEmpty()) {
 720                 htmltree.add("()");
 721             } else {
 722                 parameters.add(")");
 723                 htmltree.add(Entity.ZERO_WIDTH_SPACE);
 724                 htmltree.add("(");
 725                 htmltree.add(HtmlTree.SPAN(HtmlStyle.arguments, parameters));
 726             }
 727 
 728             // Exceptions
 729             if (exceptions != null && !exceptions.isEmpty()) {
 730                 CharSequence indent = makeSpace(indentSize + 1 - 7);
 731                 htmltree.add(DocletConstants.NL);
 732                 htmltree.add(indent);
 733                 htmltree.add("throws ");
 734                 htmltree.add(HtmlTree.SPAN(HtmlStyle.exceptions, exceptions));
 735             }
 736         }
 737     }
 738 }


  29 import java.util.List;
  30 import java.util.Set;
  31 import java.util.TreeSet;
  32 import java.util.stream.Collectors;
  33 
  34 import javax.lang.model.element.Element;
  35 import javax.lang.model.element.ExecutableElement;
  36 import javax.lang.model.element.Modifier;
  37 import javax.lang.model.element.TypeElement;
  38 import javax.lang.model.element.TypeParameterElement;
  39 import javax.lang.model.type.TypeMirror;
  40 
  41 import com.sun.source.doctree.DocTree;
  42 
  43 import jdk.javadoc.internal.doclets.formats.html.markup.ContentBuilder;
  44 import jdk.javadoc.internal.doclets.formats.html.markup.Entity;
  45 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle;
  46 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTag;
  47 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;
  48 import jdk.javadoc.internal.doclets.formats.html.markup.Links;

  49 import jdk.javadoc.internal.doclets.formats.html.markup.Table;
  50 import jdk.javadoc.internal.doclets.formats.html.markup.TableHeader;
  51 import jdk.javadoc.internal.doclets.toolkit.Content;
  52 import jdk.javadoc.internal.doclets.toolkit.MemberSummaryWriter;
  53 import jdk.javadoc.internal.doclets.toolkit.Resources;
  54 import jdk.javadoc.internal.doclets.toolkit.taglets.DeprecatedTaglet;

  55 import jdk.javadoc.internal.doclets.toolkit.util.Utils;
  56 
  57 import static javax.lang.model.element.Modifier.ABSTRACT;
  58 import static javax.lang.model.element.Modifier.NATIVE;
  59 import static javax.lang.model.element.Modifier.PUBLIC;
  60 import static javax.lang.model.element.Modifier.STRICTFP;
  61 import static javax.lang.model.element.Modifier.SYNCHRONIZED;
  62 
  63 /**
  64  * The base class for member writers.
  65  *
  66  *  <p><b>This is NOT part of any supported API.
  67  *  If you write code that depends on this, you do so at your own risk.
  68  *  This code and its internal interfaces are subject to change or
  69  *  deletion without notice.</b>
  70  *
  71  * @author Robert Field
  72  * @author Atul M Dambalkar
  73  * @author Jamie Ho (Re-write)
  74  * @author Bhavesh Patel (Modified)


 202             TypeElement typeElement, Element member, Content tdSummary);
 203 
 204     /**
 205      * Add the inherited summary link for the member.
 206      *
 207      * @param typeElement the TypeElement to be documented
 208      * @param member the member to be documented
 209      * @param linksTree the content tree to which the inherited summary link will be added
 210      */
 211     protected abstract void addInheritedSummaryLink(TypeElement typeElement,
 212             Element member, Content linksTree);
 213 
 214     /**
 215      * Get the deprecated link.
 216      *
 217      * @param member the member being linked to
 218      * @return a content tree representing the link
 219      */
 220     protected abstract Content getDeprecatedLink(Element member);
 221 
 222     /**
 223      * Add the member name to the content tree.
 224      *
 225      * @param name the member name to be added to the content tree.
 226      * @param htmltree the content tree to which the name will be added.
 227      */
 228     protected void addName(String name, Content htmltree) {
 229         htmltree.add(name);
 230     }
 231 
 232     /**
 233      * Add the modifier for the member. The modifiers are ordered as specified
 234      * by <em>The Java Language Specification</em>.
 235      *
 236      * @param member the member for which the modifier will be added.
 237      * @param htmltree the content tree to which the modifier information will be added.
 238      */
 239     protected void addModifiers(Element member, Content htmltree) {
 240         Set<Modifier> set = new TreeSet<>(member.getModifiers());
 241 
 242         // remove the ones we really don't need
 243         set.remove(NATIVE);
 244         set.remove(SYNCHRONIZED);
 245         set.remove(STRICTFP);
 246 
 247         // According to JLS, we should not be showing public modifier for
 248         // interface methods.
 249         if ((utils.isField(member) || utils.isMethod(member))
 250             && ((writer instanceof ClassWriterImpl
 251                  && utils.isInterface(((ClassWriterImpl) writer).getTypeElement())  ||
 252                  writer instanceof AnnotationTypeWriterImpl) )) {
 253             // Remove the implicit abstract and public modifiers
 254             if (utils.isMethod(member) &&
 255                 (utils.isInterface(member.getEnclosingElement()) ||
 256                  utils.isAnnotationType(member.getEnclosingElement()))) {
 257                 set.remove(ABSTRACT);
 258                 set.remove(PUBLIC);
 259             }
 260             if (!utils.isMethod(member)) {
 261                 set.remove(PUBLIC);
 262             }
 263         }
 264         if (!set.isEmpty()) {
 265             String mods = set.stream().map(Modifier::toString).collect(Collectors.joining(" "));
 266             htmltree.add(mods);
 267             htmltree.add(Entity.NO_BREAK_SPACE);
 268         }
 269     }
 270 
 271     protected CharSequence makeSpace(int len) {
 272         if (len <= 0) {
 273             return "";
 274         }
 275         StringBuilder sb = new StringBuilder(len);
 276         for (int i = 0; i < len; i++) {
 277             sb.append(' ');
 278         }
 279         return sb;
 280     }
 281 
 282     /**
 283      * Add the modifier and type for the member in the member summary.
 284      *
 285      * @param member the member to add the type for
 286      * @param type the type to add
 287      * @param tdSummaryType the content tree to which the modified and type will be added
 288      */
 289     protected void addModifierAndType(Element member, TypeMirror type,
 290             Content tdSummaryType) {


 534         }
 535         Table table = getSummaryTable();
 536         if (table.needsScript()) {
 537             writer.getMainBodyScript().append(table.getScript());
 538         }
 539         return table.toContent();
 540     }
 541 
 542     /**
 543      * Get the member tree to be documented.
 544      *
 545      * @param memberTree the content tree of member to be documented
 546      * @return a content tree that will be added to the class documentation
 547      */
 548     @Override
 549     public Content getMemberTree(Content memberTree) {
 550         return writer.getMemberTree(memberTree);
 551     }
 552 
 553     /**
 554      * Get the member tree to be documented.
 555      *
 556      * @param memberTree the content tree of member to be documented
 557      * @param isLastContent true if the content to be added is the last content
 558      * @return a content tree that will be added to the class documentation
 559      */
 560     public Content getMemberTree(Content memberTree, boolean isLastContent) {
 561         if (isLastContent)
 562             return HtmlTree.LI(HtmlStyle.blockListLast, memberTree);
 563         else
 564             return HtmlTree.LI(HtmlStyle.blockList, memberTree);































































































































































































































 565     }
 566 }
< prev index next >