< prev index next >

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

Print this page




  34 import java.util.Locale;
  35 import java.util.Map;
  36 import java.util.Set;
  37 import java.util.regex.Matcher;
  38 import java.util.regex.Pattern;
  39 
  40 import javax.lang.model.element.AnnotationMirror;
  41 import javax.lang.model.element.AnnotationValue;
  42 import javax.lang.model.element.Element;
  43 import javax.lang.model.element.ElementKind;
  44 import javax.lang.model.element.ExecutableElement;
  45 import javax.lang.model.element.ModuleElement;
  46 import javax.lang.model.element.Name;
  47 import javax.lang.model.element.PackageElement;
  48 import javax.lang.model.element.QualifiedNameable;
  49 import javax.lang.model.element.TypeElement;
  50 import javax.lang.model.element.VariableElement;
  51 import javax.lang.model.type.DeclaredType;
  52 import javax.lang.model.type.TypeMirror;
  53 import javax.lang.model.util.SimpleAnnotationValueVisitor9;
  54 import javax.lang.model.util.SimpleElementVisitor9;
  55 import javax.lang.model.util.SimpleTypeVisitor9;
  56 
  57 import com.sun.source.doctree.AttributeTree;
  58 import com.sun.source.doctree.AttributeTree.ValueKind;
  59 import com.sun.source.doctree.CommentTree;
  60 import com.sun.source.doctree.DocRootTree;
  61 import com.sun.source.doctree.DocTree;
  62 import com.sun.source.doctree.DocTree.Kind;
  63 import com.sun.source.doctree.EndElementTree;
  64 import com.sun.source.doctree.EntityTree;
  65 import com.sun.source.doctree.ErroneousTree;
  66 import com.sun.source.doctree.IndexTree;
  67 import com.sun.source.doctree.InheritDocTree;
  68 import com.sun.source.doctree.LinkTree;
  69 import com.sun.source.doctree.LiteralTree;
  70 import com.sun.source.doctree.SeeTree;
  71 import com.sun.source.doctree.StartElementTree;
  72 import com.sun.source.doctree.SummaryTree;
  73 import com.sun.source.doctree.SystemPropertyTree;
  74 import com.sun.source.doctree.TextTree;


1495                             tag, getTagletWriterInstance(isFirstSentence));
1496                     result.add(output);
1497                     // if we obtained the first sentence successfully, nothing more to do
1498                     return (isFirstSentence && !output.isEmpty());
1499                 }
1500 
1501                 @Override
1502                 public Boolean visitIndex(IndexTree node, Content p) {
1503                     Content output = TagletWriter.getInlineTagOutput(element,
1504                             configuration.tagletManager, holderTag, tag,
1505                             getTagletWriterInstance(isFirstSentence, inSummary));
1506                     if (output != null) {
1507                         result.add(output);
1508                     }
1509                     return false;
1510                 }
1511 
1512                 @Override
1513                 public Boolean visitLink(LinkTree node, Content c) {
1514                     // we need to pass the DocTreeImpl here, so ignore node
1515                     result.add(seeTagToContent(element, tag));

1516                     return false;
1517                 }
1518 
1519                 @Override
1520                 public Boolean visitLiteral(LiteralTree node, Content c) {
1521                     String s = node.getBody().getBody();
1522                     Content content = new StringContent(utils.normalizeNewlines(s));
1523                     if (node.getKind() == CODE)
1524                         content = HtmlTree.CODE(content);
1525                     result.add(content);
1526                     return false;
1527                 }
1528 
1529                 @Override
1530                 public Boolean visitSee(SeeTree node, Content c) {
1531                     // we need to pass the DocTreeImpl here, so ignore node
1532                     result.add(seeTagToContent(element, tag));
1533                     return false;
1534                 }
1535 


1643      * that relative link will no longer work.  We should redirect those links
1644      * so that they will work again.
1645      * <p>
1646      * Here is the algorithm used to fix the link:
1647      * <p>
1648      * {@literal <relative link> => docRoot + <relative path to file> + <relative link> }
1649      * <p>
1650      * For example, suppose DocletEnvironment has this link:
1651      * {@literal <a href="package-summary.html">The package Page</a> }
1652      * <p>
1653      * If this link appeared in the index, we would redirect
1654      * the link like this:
1655      *
1656      * {@literal <a href="./jdk/javadoc/doclet/package-summary.html">The package Page</a>}
1657      *
1658      * @param element the Element object whose documentation is being written.
1659      * @param tt the text being written.
1660      *
1661      * @return the text, with all the relative links redirected to work.
1662      */

1663     private String redirectRelativeLinks(Element element, TextTree tt) {
1664         String text = tt.getBody();
1665         if (element == null || utils.isOverviewElement(element) || shouldNotRedirectRelativeLinks()) {
1666             return text;
1667         }
1668 
1669         DocPath redirectPathFromRoot = new SimpleElementVisitor9<DocPath, Void>() {
1670             @Override
1671             public DocPath visitType(TypeElement e, Void p) {
1672                 return docPaths.forPackage(utils.containingPackage(e));
1673             }
1674 
1675             @Override
1676             public DocPath visitPackage(PackageElement e, Void p) {
1677                 return docPaths.forPackage(e);
1678             }
1679 
1680             @Override
1681             public DocPath visitVariable(VariableElement e, Void p) {
1682                 return docPaths.forPackage(utils.containingPackage(e));
1683             }
1684 
1685             @Override
1686             public DocPath visitExecutable(ExecutableElement e, Void p) {
1687                 return docPaths.forPackage(utils.containingPackage(e));
1688             }
1689 


1732      * is that all necessary checks have been made to get here.
1733      */
1734     public void addReceiverAnnotationInfo(ExecutableElement method, TypeMirror rcvrTypeMirror,
1735             List<? extends AnnotationMirror> annotationMirrors, Content htmltree) {
1736         TypeMirror rcvrType = method.getReceiverType();
1737         List<? extends AnnotationMirror> annotationMirrors1 = rcvrType.getAnnotationMirrors();
1738         htmltree.add(getAnnotationInfo(annotationMirrors1, false));
1739     }
1740 
1741     /**
1742      * Adds the annotation types for the given element.
1743      *
1744      * @param element the package to write annotations for
1745      * @param htmltree the content tree to which the annotation types will be added
1746      */
1747     public void addAnnotationInfo(Element element, Content htmltree) {
1748         addAnnotationInfo(element.getAnnotationMirrors(), htmltree);
1749     }
1750 
1751     /**
1752      * Add the annotatation types for the given element and parameter.
1753      *
1754      * @param param the parameter to write annotations for.
1755      * @param tree the content tree to which the annotation types will be added
1756      */
1757     public boolean addAnnotationInfo(VariableElement param, Content tree) {
1758         Content annotaionInfo = getAnnotationInfo(param.getAnnotationMirrors(), false);
1759         if (annotaionInfo.isEmpty()) {
1760             return false;
1761         }
1762         tree.add(annotaionInfo);
1763         return true;
1764     }
1765 
1766     /**
1767      * Adds the annotatation types for the given Element.
1768      *
1769      * @param descList a list of annotation mirrors.
1770      * @param htmltree the documentation tree to which the annotation info will be
1771      *        added
1772      */
1773     private void addAnnotationInfo(List<? extends AnnotationMirror> descList, Content htmltree) {
1774         htmltree.add(getAnnotationInfo(descList, true));
1775     }
1776 
1777     /**
1778      * Return a content tree containing the annotation types for the given element.
1779      *
1780      * @param descList a list of annotation mirrors.
1781      * @return the documentation tree containing the annotation info.
1782      */
1783     Content getAnnotationInfo(List<? extends AnnotationMirror> descList, boolean lineBreak) {
1784         List<Content> annotations = getAnnotations(descList, lineBreak);
1785         String sep = "";
1786         ContentBuilder builder = new ContentBuilder();
1787         for (Content annotation: annotations) {




  34 import java.util.Locale;
  35 import java.util.Map;
  36 import java.util.Set;
  37 import java.util.regex.Matcher;
  38 import java.util.regex.Pattern;
  39 
  40 import javax.lang.model.element.AnnotationMirror;
  41 import javax.lang.model.element.AnnotationValue;
  42 import javax.lang.model.element.Element;
  43 import javax.lang.model.element.ElementKind;
  44 import javax.lang.model.element.ExecutableElement;
  45 import javax.lang.model.element.ModuleElement;
  46 import javax.lang.model.element.Name;
  47 import javax.lang.model.element.PackageElement;
  48 import javax.lang.model.element.QualifiedNameable;
  49 import javax.lang.model.element.TypeElement;
  50 import javax.lang.model.element.VariableElement;
  51 import javax.lang.model.type.DeclaredType;
  52 import javax.lang.model.type.TypeMirror;
  53 import javax.lang.model.util.SimpleAnnotationValueVisitor9;
  54 import javax.lang.model.util.SimpleElementVisitor14;
  55 import javax.lang.model.util.SimpleTypeVisitor9;
  56 
  57 import com.sun.source.doctree.AttributeTree;
  58 import com.sun.source.doctree.AttributeTree.ValueKind;
  59 import com.sun.source.doctree.CommentTree;
  60 import com.sun.source.doctree.DocRootTree;
  61 import com.sun.source.doctree.DocTree;
  62 import com.sun.source.doctree.DocTree.Kind;
  63 import com.sun.source.doctree.EndElementTree;
  64 import com.sun.source.doctree.EntityTree;
  65 import com.sun.source.doctree.ErroneousTree;
  66 import com.sun.source.doctree.IndexTree;
  67 import com.sun.source.doctree.InheritDocTree;
  68 import com.sun.source.doctree.LinkTree;
  69 import com.sun.source.doctree.LiteralTree;
  70 import com.sun.source.doctree.SeeTree;
  71 import com.sun.source.doctree.StartElementTree;
  72 import com.sun.source.doctree.SummaryTree;
  73 import com.sun.source.doctree.SystemPropertyTree;
  74 import com.sun.source.doctree.TextTree;


1495                             tag, getTagletWriterInstance(isFirstSentence));
1496                     result.add(output);
1497                     // if we obtained the first sentence successfully, nothing more to do
1498                     return (isFirstSentence && !output.isEmpty());
1499                 }
1500 
1501                 @Override
1502                 public Boolean visitIndex(IndexTree node, Content p) {
1503                     Content output = TagletWriter.getInlineTagOutput(element,
1504                             configuration.tagletManager, holderTag, tag,
1505                             getTagletWriterInstance(isFirstSentence, inSummary));
1506                     if (output != null) {
1507                         result.add(output);
1508                     }
1509                     return false;
1510                 }
1511 
1512                 @Override
1513                 public Boolean visitLink(LinkTree node, Content c) {
1514                     // we need to pass the DocTreeImpl here, so ignore node
1515                     Content content = seeTagToContent(element, tag);
1516                     result.add(content);
1517                     return false;
1518                 }
1519 
1520                 @Override
1521                 public Boolean visitLiteral(LiteralTree node, Content c) {
1522                     String s = node.getBody().getBody();
1523                     Content content = new StringContent(utils.normalizeNewlines(s));
1524                     if (node.getKind() == CODE)
1525                         content = HtmlTree.CODE(content);
1526                     result.add(content);
1527                     return false;
1528                 }
1529 
1530                 @Override
1531                 public Boolean visitSee(SeeTree node, Content c) {
1532                     // we need to pass the DocTreeImpl here, so ignore node
1533                     result.add(seeTagToContent(element, tag));
1534                     return false;
1535                 }
1536 


1644      * that relative link will no longer work.  We should redirect those links
1645      * so that they will work again.
1646      * <p>
1647      * Here is the algorithm used to fix the link:
1648      * <p>
1649      * {@literal <relative link> => docRoot + <relative path to file> + <relative link> }
1650      * <p>
1651      * For example, suppose DocletEnvironment has this link:
1652      * {@literal <a href="package-summary.html">The package Page</a> }
1653      * <p>
1654      * If this link appeared in the index, we would redirect
1655      * the link like this:
1656      *
1657      * {@literal <a href="./jdk/javadoc/doclet/package-summary.html">The package Page</a>}
1658      *
1659      * @param element the Element object whose documentation is being written.
1660      * @param tt the text being written.
1661      *
1662      * @return the text, with all the relative links redirected to work.
1663      */
1664     @SuppressWarnings("preview")
1665     private String redirectRelativeLinks(Element element, TextTree tt) {
1666         String text = tt.getBody();
1667         if (element == null || utils.isOverviewElement(element) || shouldNotRedirectRelativeLinks()) {
1668             return text;
1669         }
1670 
1671         DocPath redirectPathFromRoot = new SimpleElementVisitor14<DocPath, Void>() {
1672             @Override
1673             public DocPath visitType(TypeElement e, Void p) {
1674                 return docPaths.forPackage(utils.containingPackage(e));
1675             }
1676 
1677             @Override
1678             public DocPath visitPackage(PackageElement e, Void p) {
1679                 return docPaths.forPackage(e);
1680             }
1681 
1682             @Override
1683             public DocPath visitVariable(VariableElement e, Void p) {
1684                 return docPaths.forPackage(utils.containingPackage(e));
1685             }
1686 
1687             @Override
1688             public DocPath visitExecutable(ExecutableElement e, Void p) {
1689                 return docPaths.forPackage(utils.containingPackage(e));
1690             }
1691 


1734      * is that all necessary checks have been made to get here.
1735      */
1736     public void addReceiverAnnotationInfo(ExecutableElement method, TypeMirror rcvrTypeMirror,
1737             List<? extends AnnotationMirror> annotationMirrors, Content htmltree) {
1738         TypeMirror rcvrType = method.getReceiverType();
1739         List<? extends AnnotationMirror> annotationMirrors1 = rcvrType.getAnnotationMirrors();
1740         htmltree.add(getAnnotationInfo(annotationMirrors1, false));
1741     }
1742 
1743     /**
1744      * Adds the annotation types for the given element.
1745      *
1746      * @param element the package to write annotations for
1747      * @param htmltree the content tree to which the annotation types will be added
1748      */
1749     public void addAnnotationInfo(Element element, Content htmltree) {
1750         addAnnotationInfo(element.getAnnotationMirrors(), htmltree);
1751     }
1752 
1753     /**
1754      * Add the annotation types for the given element and parameter.
1755      *
1756      * @param param the parameter to write annotations for.
1757      * @param tree the content tree to which the annotation types will be added
1758      */
1759     public boolean addAnnotationInfo(VariableElement param, Content tree) {
1760         Content annotationInfo = getAnnotationInfo(param.getAnnotationMirrors(), false);
1761         if (annotationInfo.isEmpty()) {
1762             return false;
1763         }
1764         tree.add(annotationInfo);
1765         return true;
1766     }
1767 
1768     /**
1769      * Adds the annotation types for the given Element.
1770      *
1771      * @param descList a list of annotation mirrors.
1772      * @param htmltree the documentation tree to which the annotation info will be
1773      *        added
1774      */
1775     private void addAnnotationInfo(List<? extends AnnotationMirror> descList, Content htmltree) {
1776         htmltree.add(getAnnotationInfo(descList, true));
1777     }
1778 
1779     /**
1780      * Return a content tree containing the annotation types for the given element.
1781      *
1782      * @param descList a list of annotation mirrors.
1783      * @return the documentation tree containing the annotation info.
1784      */
1785     Content getAnnotationInfo(List<? extends AnnotationMirror> descList, boolean lineBreak) {
1786         List<Content> annotations = getAnnotations(descList, lineBreak);
1787         String sep = "";
1788         ContentBuilder builder = new ContentBuilder();
1789         for (Content annotation: annotations) {


< prev index next >