1698 return text;
1699 }
1700
1701 /**
1702 * According to
1703 * <cite>The Java™ Language Specification</cite>,
1704 * all the outer classes and static nested classes are core classes.
1705 */
1706 public boolean isCoreClass(TypeElement typeElement) {
1707 return utils.getEnclosingTypeElement(typeElement) == null || utils.isStatic(typeElement);
1708 }
1709
1710 /**
1711 * Adds the annotation types for the given packageElement.
1712 *
1713 * @param packageElement the package to write annotations for.
1714 * @param htmltree the documentation tree to which the annotation info will be
1715 * added
1716 */
1717 public void addAnnotationInfo(PackageElement packageElement, Content htmltree) {
1718 addAnnotationInfo(packageElement, packageElement.getAnnotationMirrors(), htmltree);
1719 }
1720
1721 /**
1722 * Add the annotation types of the executable receiver.
1723 *
1724 * @param method the executable to write the receiver annotations for.
1725 * @param descList a list of annotation mirrors.
1726 * @param htmltree the documentation tree to which the annotation info will be
1727 * added
1728 */
1729 public void addReceiverAnnotationInfo(ExecutableElement method, List<AnnotationMirror> descList,
1730 Content htmltree) {
1731 addAnnotationInfo(0, method, descList, false, htmltree);
1732 }
1733
1734 /*
1735 * this is a hack to delay dealing with Annotations in the writers, the assumption
1736 * is that all necessary checks have been made to get here.
1737 */
1738 public void addReceiverAnnotationInfo(ExecutableElement method, TypeMirror rcvrTypeMirror,
1739 List<? extends AnnotationMirror> annotationMirrors, Content htmltree) {
1740 TypeMirror rcvrType = method.getReceiverType();
1741 List<? extends AnnotationMirror> annotationMirrors1 = rcvrType.getAnnotationMirrors();
1742 addAnnotationInfo(0, method, annotationMirrors1, false, htmltree);
1743 }
1744
1745 /**
1746 * Adds the annotation types for the given element.
1747 *
1748 * @param element the package to write annotations for
1749 * @param htmltree the content tree to which the annotation types will be added
1750 */
1751 public void addAnnotationInfo(Element element, Content htmltree) {
1752 addAnnotationInfo(element, element.getAnnotationMirrors(), htmltree);
1753 }
1754
1755 /**
1756 * Add the annotatation types for the given element and parameter.
1757 *
1758 * @param indent the number of spaces to indent the parameters.
1759 * @param element the element to write annotations for.
1760 * @param param the parameter to write annotations for.
1761 * @param tree the content tree to which the annotation types will be added
1762 */
1763 public boolean addAnnotationInfo(int indent, Element element, VariableElement param,
1764 Content tree) {
1765 return addAnnotationInfo(indent, element, param.getAnnotationMirrors(), false, tree);
1766 }
1767
1768 /**
1769 * Adds the annotatation types for the given Element.
1770 *
1771 * @param element the element to write annotations for.
1772 * @param descList a list of annotation mirrors.
1773 * @param htmltree the documentation tree to which the annotation info will be
1774 * added
1775 */
1776 private void addAnnotationInfo(Element element, List<? extends AnnotationMirror> descList,
1777 Content htmltree) {
1778 addAnnotationInfo(0, element, descList, true, htmltree);
1779 }
1780
1781 /**
1782 * Adds the annotation types for the given element.
1783 *
1784 * @param indent the number of extra spaces to indent the annotations.
1785 * @param element the element to write annotations for.
1786 * @param descList a list of annotation mirrors.
1787 * @param htmltree the documentation tree to which the annotation info will be
1788 * added
1789 */
1790 private boolean addAnnotationInfo(int indent, Element element,
1791 List<? extends AnnotationMirror> descList, boolean lineBreak, Content htmltree) {
1792 List<Content> annotations = getAnnotations(indent, descList, lineBreak);
1793 String sep = "";
1794 if (annotations.isEmpty()) {
1795 return false;
1796 }
1797 for (Content annotation: annotations) {
1798 htmltree.add(sep);
1799 htmltree.add(annotation);
1800 if (!lineBreak) {
1801 sep = " ";
1802 }
1803 }
1804 return true;
1805 }
1806
1807 /**
1808 * Return the string representations of the annotation types for
1809 * the given doc.
1810 *
1811 * @param indent the number of extra spaces to indent the annotations.
1812 * @param descList a list of annotation mirrors.
1813 * @param linkBreak if true, add new line between each member value.
1814 * @return a list of strings representing the annotations being
1815 * documented.
1816 */
1817 private List<Content> getAnnotations(int indent, List<? extends AnnotationMirror> descList, boolean linkBreak) {
1818 return getAnnotations(indent, descList, linkBreak, true);
1819 }
1820
1821 private List<Content> getAnnotations(int indent, AnnotationMirror amirror, boolean linkBreak) {
1822 List<AnnotationMirror> descList = new ArrayList<>();
1823 descList.add(amirror);
1824 return getAnnotations(indent, descList, linkBreak, true);
1825 }
1826
1827 /**
1828 * Return the string representations of the annotation types for
1829 * the given doc.
1830 *
1831 * A {@code null} {@code elementType} indicates that all the
1832 * annotations should be returned without any filtering.
1833 *
1834 * @param indent the number of extra spaces to indent the annotations.
1835 * @param descList a list of annotation mirrors.
1836 * @param linkBreak if true, add new line between each member value.
1837 * @param isJava5DeclarationLocation
1838 * @return a list of strings representing the annotations being
1839 * documented.
1840 */
1841 public List<Content> getAnnotations(int indent, List<? extends AnnotationMirror> descList,
1842 boolean linkBreak, boolean isJava5DeclarationLocation) {
1843 List<Content> results = new ArrayList<>();
1844 ContentBuilder annotation;
1845 for (AnnotationMirror aDesc : descList) {
1846 TypeElement annotationElement = (TypeElement)aDesc.getAnnotationType().asElement();
1847 // If an annotation is not documented, do not add it to the list. If
1848 // the annotation is of a repeatable type, and if it is not documented
1849 // and also if its container annotation is not documented, do not add it
1850 // to the list. If an annotation of a repeatable type is not documented
1851 // but its container is documented, it will be added to the list.
1852 if (!utils.isDocumentedAnnotation(annotationElement) &&
1853 (!isAnnotationDocumented && !isContainerDocumented)) {
1854 continue;
1855 }
1856 /* TODO: check logic here to correctly handle declaration
1857 * and type annotations.
1858 if (utils.isDeclarationAnnotation(annotationElement, isJava5DeclarationLocation)) {
1859 continue;
1860 }*/
1861 annotation = new ContentBuilder();
1862 isAnnotationDocumented = false;
1863 LinkInfoImpl linkInfo = new LinkInfoImpl(configuration,
1864 LinkInfoImpl.Kind.ANNOTATION, annotationElement);
1865 Map<? extends ExecutableElement, ? extends AnnotationValue> pairs = aDesc.getElementValues();
1866 // If the annotation is synthesized, do not print the container.
1867 if (utils.configuration.workArounds.isSynthesized(aDesc)) {
1868 for (ExecutableElement ee : pairs.keySet()) {
1869 AnnotationValue annotationValue = pairs.get(ee);
1870 List<AnnotationValue> annotationTypeValues = new ArrayList<>();
1871
1872 new SimpleAnnotationValueVisitor9<Void, List<AnnotationValue>>() {
1873 @Override
1874 public Void visitArray(List<? extends AnnotationValue> vals, List<AnnotationValue> p) {
1875 p.addAll(vals);
1876 return null;
1877 }
1878
1879 @Override
1880 protected Void defaultAction(Object o, List<AnnotationValue> p) {
1883 }
1884 }.visit(annotationValue, annotationTypeValues);
1885
1886 String sep = "";
1887 for (AnnotationValue av : annotationTypeValues) {
1888 annotation.add(sep);
1889 annotation.add(annotationValueToContent(av));
1890 sep = " ";
1891 }
1892 }
1893 } else if (isAnnotationArray(pairs)) {
1894 // If the container has 1 or more value defined and if the
1895 // repeatable type annotation is not documented, do not print
1896 // the container.
1897 if (pairs.size() == 1 && isAnnotationDocumented) {
1898 List<AnnotationValue> annotationTypeValues = new ArrayList<>();
1899 for (AnnotationValue a : pairs.values()) {
1900 new SimpleAnnotationValueVisitor9<Void, List<AnnotationValue>>() {
1901 @Override
1902 public Void visitArray(List<? extends AnnotationValue> vals, List<AnnotationValue> annotationTypeValues) {
1903 for (AnnotationValue av : vals) {
1904 annotationTypeValues.add(av);
1905 }
1906 return null;
1907 }
1908 }.visit(a, annotationTypeValues);
1909 }
1910 String sep = "";
1911 for (AnnotationValue av : annotationTypeValues) {
1912 annotation.add(sep);
1913 annotation.add(annotationValueToContent(av));
1914 sep = " ";
1915 }
1916 }
1917 // If the container has 1 or more value defined and if the
1918 // repeatable type annotation is not documented, print the container.
1919 else {
1920 addAnnotations(annotationElement, linkInfo, annotation, pairs,
1921 indent, false);
1922 }
1923 }
1924 else {
1925 addAnnotations(annotationElement, linkInfo, annotation, pairs,
1926 indent, linkBreak);
1927 }
1928 annotation.add(linkBreak ? DocletConstants.NL : "");
1929 results.add(annotation);
1930 }
1931 return results;
1932 }
1933
1934 /**
1935 * Add annotation to the annotation string.
1936 *
1937 * @param annotationDoc the annotation being documented
1938 * @param linkInfo the information about the link
1939 * @param annotation the annotation string to which the annotation will be added
1940 * @param map annotation type element to annotation value pairs
1941 * @param indent the number of extra spaces to indent the annotations.
1942 * @param linkBreak if true, add new line between each member value
1943 */
1944 private void addAnnotations(TypeElement annotationDoc, LinkInfoImpl linkInfo,
1945 ContentBuilder annotation,
1946 Map<? extends ExecutableElement, ? extends AnnotationValue> map,
1947 int indent, boolean linkBreak) {
1948 linkInfo.label = new StringContent("@");
1949 linkInfo.label.add(annotationDoc.getSimpleName());
1950 annotation.add(getLink(linkInfo));
1951 if (!map.isEmpty()) {
1952 annotation.add("(");
1953 boolean isFirst = true;
1954 Set<? extends ExecutableElement> keys = map.keySet();
1955 boolean multipleValues = keys.size() > 1;
1956 for (ExecutableElement element : keys) {
1957 if (isFirst) {
1958 isFirst = false;
1959 } else {
1960 annotation.add(",");
1961 if (linkBreak) {
1962 annotation.add(DocletConstants.NL);
1963 int spaces = annotationDoc.getSimpleName().length() + 2;
1964 for (int k = 0; k < (spaces + indent); k++) {
1965 annotation.add(" ");
1966 }
1967 }
1968 }
1969 String simpleName = element.getSimpleName().toString();
1970 if (multipleValues || !"value".equals(simpleName)) { // Omit "value=" where unnecessary
1971 annotation.add(getDocLink(LinkInfoImpl.Kind.ANNOTATION,
1972 element, simpleName, false));
1973 annotation.add("=");
1974 }
1975 AnnotationValue annotationValue = map.get(element);
1976 List<AnnotationValue> annotationTypeValues = new ArrayList<>();
1977 new SimpleAnnotationValueVisitor9<Void, AnnotationValue>() {
1978 @Override
1979 public Void visitArray(List<? extends AnnotationValue> vals, AnnotationValue p) {
1980 annotationTypeValues.addAll(vals);
1981 return null;
1982 }
1983 @Override
1984 protected Void defaultAction(Object o, AnnotationValue p) {
2057 public Content visitType(TypeMirror t, Void p) {
2058 return new SimpleTypeVisitor9<Content, Void>() {
2059 @Override
2060 public Content visitDeclared(DeclaredType t, Void p) {
2061 LinkInfoImpl linkInfo = new LinkInfoImpl(configuration,
2062 LinkInfoImpl.Kind.ANNOTATION, t);
2063 String name = utils.isIncluded(t.asElement())
2064 ? t.asElement().getSimpleName().toString()
2065 : utils.getFullyQualifiedName(t.asElement());
2066 linkInfo.label = new StringContent(name + utils.getDimension(t) + ".class");
2067 return getLink(linkInfo);
2068 }
2069 @Override
2070 protected Content defaultAction(TypeMirror e, Void p) {
2071 return new StringContent(t + utils.getDimension(t) + ".class");
2072 }
2073 }.visit(t);
2074 }
2075 @Override
2076 public Content visitAnnotation(AnnotationMirror a, Void p) {
2077 List<Content> list = getAnnotations(0, a, false);
2078 ContentBuilder buf = new ContentBuilder();
2079 for (Content c : list) {
2080 buf.add(c);
2081 }
2082 return buf;
2083 }
2084 @Override
2085 public Content visitEnumConstant(VariableElement c, Void p) {
2086 return getDocLink(LinkInfoImpl.Kind.ANNOTATION,
2087 c, c.getSimpleName(), false);
2088 }
2089 @Override
2090 public Content visitArray(List<? extends AnnotationValue> vals, Void p) {
2091 ContentBuilder buf = new ContentBuilder();
2092 String sep = "";
2093 for (AnnotationValue av : vals) {
2094 buf.add(sep);
2095 buf.add(visit(av));
2096 sep = " ";
2097 }
|
1698 return text;
1699 }
1700
1701 /**
1702 * According to
1703 * <cite>The Java™ Language Specification</cite>,
1704 * all the outer classes and static nested classes are core classes.
1705 */
1706 public boolean isCoreClass(TypeElement typeElement) {
1707 return utils.getEnclosingTypeElement(typeElement) == null || utils.isStatic(typeElement);
1708 }
1709
1710 /**
1711 * Adds the annotation types for the given packageElement.
1712 *
1713 * @param packageElement the package to write annotations for.
1714 * @param htmltree the documentation tree to which the annotation info will be
1715 * added
1716 */
1717 public void addAnnotationInfo(PackageElement packageElement, Content htmltree) {
1718 addAnnotationInfo(packageElement.getAnnotationMirrors(), htmltree);
1719 }
1720
1721 /*
1722 * this is a hack to delay dealing with Annotations in the writers, the assumption
1723 * is that all necessary checks have been made to get here.
1724 */
1725 public void addReceiverAnnotationInfo(ExecutableElement method, TypeMirror rcvrTypeMirror,
1726 List<? extends AnnotationMirror> annotationMirrors, Content htmltree) {
1727 TypeMirror rcvrType = method.getReceiverType();
1728 List<? extends AnnotationMirror> annotationMirrors1 = rcvrType.getAnnotationMirrors();
1729 htmltree.add(getAnnotationInfo(annotationMirrors1, false));
1730 }
1731
1732 /**
1733 * Adds the annotation types for the given element.
1734 *
1735 * @param element the package to write annotations for
1736 * @param htmltree the content tree to which the annotation types will be added
1737 */
1738 public void addAnnotationInfo(Element element, Content htmltree) {
1739 addAnnotationInfo(element.getAnnotationMirrors(), htmltree);
1740 }
1741
1742 /**
1743 * Add the annotatation types for the given element and parameter.
1744 *
1745 * @param param the parameter to write annotations for.
1746 * @param tree the content tree to which the annotation types will be added
1747 */
1748 public boolean addAnnotationInfo(VariableElement param, Content tree) {
1749 Content annotaionInfo = getAnnotationInfo(param.getAnnotationMirrors(), false);
1750 if (annotaionInfo.isEmpty()) {
1751 return false;
1752 }
1753 tree.add(annotaionInfo);
1754 return true;
1755 }
1756
1757 /**
1758 * Adds the annotatation types for the given Element.
1759 *
1760 * @param descList a list of annotation mirrors.
1761 * @param htmltree the documentation tree to which the annotation info will be
1762 * added
1763 */
1764 private void addAnnotationInfo(List<? extends AnnotationMirror> descList, Content htmltree) {
1765 htmltree.add(getAnnotationInfo(descList, true));
1766 }
1767
1768 /**
1769 * Return a content tree containing the annotation types for the given element.
1770 *
1771 * @param descList a list of annotation mirrors.
1772 * @return the documentation tree containing the annotation info.
1773 */
1774 Content getAnnotationInfo(List<? extends AnnotationMirror> descList, boolean lineBreak) {
1775 List<Content> annotations = getAnnotations(descList, lineBreak);
1776 String sep = "";
1777 ContentBuilder builder = new ContentBuilder();
1778 for (Content annotation: annotations) {
1779 builder.add(sep);
1780 builder.add(annotation);
1781 if (!lineBreak) {
1782 sep = " ";
1783 }
1784 }
1785 return builder;
1786 }
1787
1788 /**
1789 * Return the string representations of the annotation types for
1790 * the given doc.
1791 *
1792 * @param descList a list of annotation mirrors.
1793 * @param linkBreak if true, add new line between each member value.
1794 * @return a list of strings representing the annotations being
1795 * documented.
1796 */
1797 public List<Content> getAnnotations(List<? extends AnnotationMirror> descList, boolean linkBreak) {
1798 List<Content> results = new ArrayList<>();
1799 ContentBuilder annotation;
1800 for (AnnotationMirror aDesc : descList) {
1801 TypeElement annotationElement = (TypeElement)aDesc.getAnnotationType().asElement();
1802 // If an annotation is not documented, do not add it to the list. If
1803 // the annotation is of a repeatable type, and if it is not documented
1804 // and also if its container annotation is not documented, do not add it
1805 // to the list. If an annotation of a repeatable type is not documented
1806 // but its container is documented, it will be added to the list.
1807 if (!utils.isDocumentedAnnotation(annotationElement) &&
1808 (!isAnnotationDocumented && !isContainerDocumented)) {
1809 continue;
1810 }
1811 annotation = new ContentBuilder();
1812 isAnnotationDocumented = false;
1813 LinkInfoImpl linkInfo = new LinkInfoImpl(configuration,
1814 LinkInfoImpl.Kind.ANNOTATION, annotationElement);
1815 Map<? extends ExecutableElement, ? extends AnnotationValue> pairs = aDesc.getElementValues();
1816 // If the annotation is synthesized, do not print the container.
1817 if (utils.configuration.workArounds.isSynthesized(aDesc)) {
1818 for (ExecutableElement ee : pairs.keySet()) {
1819 AnnotationValue annotationValue = pairs.get(ee);
1820 List<AnnotationValue> annotationTypeValues = new ArrayList<>();
1821
1822 new SimpleAnnotationValueVisitor9<Void, List<AnnotationValue>>() {
1823 @Override
1824 public Void visitArray(List<? extends AnnotationValue> vals, List<AnnotationValue> p) {
1825 p.addAll(vals);
1826 return null;
1827 }
1828
1829 @Override
1830 protected Void defaultAction(Object o, List<AnnotationValue> p) {
1833 }
1834 }.visit(annotationValue, annotationTypeValues);
1835
1836 String sep = "";
1837 for (AnnotationValue av : annotationTypeValues) {
1838 annotation.add(sep);
1839 annotation.add(annotationValueToContent(av));
1840 sep = " ";
1841 }
1842 }
1843 } else if (isAnnotationArray(pairs)) {
1844 // If the container has 1 or more value defined and if the
1845 // repeatable type annotation is not documented, do not print
1846 // the container.
1847 if (pairs.size() == 1 && isAnnotationDocumented) {
1848 List<AnnotationValue> annotationTypeValues = new ArrayList<>();
1849 for (AnnotationValue a : pairs.values()) {
1850 new SimpleAnnotationValueVisitor9<Void, List<AnnotationValue>>() {
1851 @Override
1852 public Void visitArray(List<? extends AnnotationValue> vals, List<AnnotationValue> annotationTypeValues) {
1853 annotationTypeValues.addAll(vals);
1854 return null;
1855 }
1856 }.visit(a, annotationTypeValues);
1857 }
1858 String sep = "";
1859 for (AnnotationValue av : annotationTypeValues) {
1860 annotation.add(sep);
1861 annotation.add(annotationValueToContent(av));
1862 sep = " ";
1863 }
1864 }
1865 // If the container has 1 or more value defined and if the
1866 // repeatable type annotation is not documented, print the container.
1867 else {
1868 addAnnotations(annotationElement, linkInfo, annotation, pairs, false);
1869 }
1870 }
1871 else {
1872 addAnnotations(annotationElement, linkInfo, annotation, pairs, linkBreak);
1873 }
1874 annotation.add(linkBreak ? DocletConstants.NL : "");
1875 results.add(annotation);
1876 }
1877 return results;
1878 }
1879
1880 /**
1881 * Add annotation to the annotation string.
1882 *
1883 * @param annotationDoc the annotation being documented
1884 * @param linkInfo the information about the link
1885 * @param annotation the annotation string to which the annotation will be added
1886 * @param map annotation type element to annotation value pairs
1887 * @param linkBreak if true, add new line between each member value
1888 */
1889 private void addAnnotations(TypeElement annotationDoc, LinkInfoImpl linkInfo,
1890 ContentBuilder annotation,
1891 Map<? extends ExecutableElement, ? extends AnnotationValue> map,
1892 boolean linkBreak) {
1893 linkInfo.label = new StringContent("@");
1894 linkInfo.label.add(annotationDoc.getSimpleName());
1895 annotation.add(getLink(linkInfo));
1896 if (!map.isEmpty()) {
1897 annotation.add("(");
1898 boolean isFirst = true;
1899 Set<? extends ExecutableElement> keys = map.keySet();
1900 boolean multipleValues = keys.size() > 1;
1901 for (ExecutableElement element : keys) {
1902 if (isFirst) {
1903 isFirst = false;
1904 } else {
1905 annotation.add(",");
1906 if (linkBreak) {
1907 annotation.add(DocletConstants.NL);
1908 int spaces = annotationDoc.getSimpleName().length() + 2;
1909 for (int k = 0; k < (spaces); k++) {
1910 annotation.add(" ");
1911 }
1912 }
1913 }
1914 String simpleName = element.getSimpleName().toString();
1915 if (multipleValues || !"value".equals(simpleName)) { // Omit "value=" where unnecessary
1916 annotation.add(getDocLink(LinkInfoImpl.Kind.ANNOTATION,
1917 element, simpleName, false));
1918 annotation.add("=");
1919 }
1920 AnnotationValue annotationValue = map.get(element);
1921 List<AnnotationValue> annotationTypeValues = new ArrayList<>();
1922 new SimpleAnnotationValueVisitor9<Void, AnnotationValue>() {
1923 @Override
1924 public Void visitArray(List<? extends AnnotationValue> vals, AnnotationValue p) {
1925 annotationTypeValues.addAll(vals);
1926 return null;
1927 }
1928 @Override
1929 protected Void defaultAction(Object o, AnnotationValue p) {
2002 public Content visitType(TypeMirror t, Void p) {
2003 return new SimpleTypeVisitor9<Content, Void>() {
2004 @Override
2005 public Content visitDeclared(DeclaredType t, Void p) {
2006 LinkInfoImpl linkInfo = new LinkInfoImpl(configuration,
2007 LinkInfoImpl.Kind.ANNOTATION, t);
2008 String name = utils.isIncluded(t.asElement())
2009 ? t.asElement().getSimpleName().toString()
2010 : utils.getFullyQualifiedName(t.asElement());
2011 linkInfo.label = new StringContent(name + utils.getDimension(t) + ".class");
2012 return getLink(linkInfo);
2013 }
2014 @Override
2015 protected Content defaultAction(TypeMirror e, Void p) {
2016 return new StringContent(t + utils.getDimension(t) + ".class");
2017 }
2018 }.visit(t);
2019 }
2020 @Override
2021 public Content visitAnnotation(AnnotationMirror a, Void p) {
2022 List<Content> list = getAnnotations(List.of(a), false);
2023 ContentBuilder buf = new ContentBuilder();
2024 for (Content c : list) {
2025 buf.add(c);
2026 }
2027 return buf;
2028 }
2029 @Override
2030 public Content visitEnumConstant(VariableElement c, Void p) {
2031 return getDocLink(LinkInfoImpl.Kind.ANNOTATION,
2032 c, c.getSimpleName(), false);
2033 }
2034 @Override
2035 public Content visitArray(List<? extends AnnotationValue> vals, Void p) {
2036 ContentBuilder buf = new ContentBuilder();
2037 String sep = "";
2038 for (AnnotationValue av : vals) {
2039 buf.add(sep);
2040 buf.add(visit(av));
2041 sep = " ";
2042 }
|