src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ValueTaglet.java

Print this page

        

*** 1,7 **** /* ! * Copyright (c) 2001, 2013, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this --- 1,7 ---- /* ! * Copyright (c) 2001, 2015, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this
*** 21,39 **** * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ ! package com.sun.tools.doclets.internal.toolkit.taglets; - import java.util.*; ! import com.sun.javadoc.*; ! import com.sun.tools.doclets.internal.toolkit.Configuration; ! import com.sun.tools.doclets.internal.toolkit.Content; ! import com.sun.tools.doclets.internal.toolkit.util.*; /** * An inline Taglet representing the value tag. This tag should only be used with * constant fields that have a value. It is used to access the value of constant * fields. This inline tag has an optional field name parameter. If the name is * specified, the constant value is retrieved from the specified field. A link --- 21,46 ---- * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ ! package jdk.javadoc.internal.doclets.toolkit.taglets; ! import javax.lang.model.element.Element; ! import javax.lang.model.element.TypeElement; ! import javax.lang.model.element.VariableElement; ! import javax.lang.model.util.Elements; + import com.sun.source.doctree.DocTree; + import jdk.javadoc.internal.doclets.toolkit.Configuration; + import jdk.javadoc.internal.doclets.toolkit.Content; + import jdk.javadoc.internal.doclets.toolkit.util.CommentHelper; + import jdk.javadoc.internal.doclets.toolkit.util.Utils; + + import static com.sun.source.doctree.DocTree.Kind.*; + /** * An inline Taglet representing the value tag. This tag should only be used with * constant fields that have a value. It is used to access the value of constant * fields. This inline tag has an optional field name parameter. If the name is * specified, the constant value is retrieved from the specified field. A link
*** 54,64 **** /** * Construct a new ValueTaglet. */ public ValueTaglet() { ! name = "value"; } /** * Will return false because this inline tag may * only appear in Fields. --- 61,71 ---- /** * Construct a new ValueTaglet. */ public ValueTaglet() { ! name = VALUE.tagName; } /** * Will return false because this inline tag may * only appear in Fields.
*** 103,188 **** public boolean inType() { return true; } /** ! * Given the name of the field, return the corresponding FieldDoc. Return null * due to invalid use of value tag if the name is null or empty string and if * the value tag is not used on a field. * * @param config the current configuration of the doclet. * @param tag the value tag. - * @param name the name of the field to search for. The name should be in - * {@code <qualified class name>#<field name>} format. If the class name is omitted, - * it is assumed that the field is in the current class. * ! * @return the corresponding FieldDoc. If the name is null or empty string, * return field that the value tag was used in. Return null if the name is null * or empty string and if the value tag is not used on a field. */ ! private FieldDoc getFieldDoc(Configuration config, Tag tag, String name) { ! if (name == null || name.length() == 0) { //Base case: no label. ! if (tag.holder() instanceof FieldDoc) { ! return (FieldDoc) tag.holder(); } else { // If the value tag does not specify a parameter which is a valid field and // it is not used within the comments of a valid field, return null. return null; } } ! StringTokenizer st = new StringTokenizer(name, "#"); String memberName = null; ! ClassDoc cd = null; ! if (st.countTokens() == 1) { //Case 2: @value in same class. ! Doc holder = tag.holder(); ! if (holder instanceof MemberDoc) { ! cd = ((MemberDoc) holder).containingClass(); ! } else if (holder instanceof ClassDoc) { ! cd = (ClassDoc) holder; } ! memberName = st.nextToken(); } else { //Case 3: @value in different class. ! cd = config.root.classNamed(st.nextToken()); ! memberName = st.nextToken(); } ! if (cd == null) { return null; } ! for (FieldDoc field : cd.fields()) { ! if (field.name().equals(memberName)) { ! return field; } } return null; } /** * {@inheritDoc} */ ! public Content getTagletOutput(Tag tag, TagletWriter writer) { ! FieldDoc field = getFieldDoc( ! writer.configuration(), tag, tag.text()); if (field == null) { ! if (tag.text().isEmpty()) { //Invalid use of @value ! writer.getMsgRetriever().warning(tag.holder().position(), "doclet.value_tag_invalid_use"); } else { //Reference is unknown. ! writer.getMsgRetriever().warning(tag.holder().position(), ! "doclet.value_tag_invalid_reference", tag.text()); } ! } else if (field.constantValue() != null) { return writer.valueTagOutput(field, ! field.constantValueExpression(), ! ! field.equals(tag.holder())); } else { //Referenced field is not a constant. ! writer.getMsgRetriever().warning(tag.holder().position(), ! "doclet.value_tag_invalid_constant", field.name()); } return writer.getOutputInstance(); } } --- 110,202 ---- public boolean inType() { return true; } /** ! * Given the name of the field, return the corresponding VariableElement. Return null * due to invalid use of value tag if the name is null or empty string and if * the value tag is not used on a field. * + * @param holder the element holding the tag * @param config the current configuration of the doclet. * @param tag the value tag. * ! * @return the corresponding VariableElement. If the name is null or empty string, * return field that the value tag was used in. Return null if the name is null * or empty string and if the value tag is not used on a field. */ ! private VariableElement getVariableElement(Element holder, Configuration config, DocTree tag) { ! Utils utils = config.utils; ! CommentHelper ch = utils.getCommentHelper(holder); ! String signature = ch.getReferencedSignature(tag); ! ! if (signature == null) { // no reference //Base case: no label. ! if (utils.isVariableElement(holder)) { ! return (VariableElement)(holder); } else { // If the value tag does not specify a parameter which is a valid field and // it is not used within the comments of a valid field, return null. return null; } } ! ! String[] sigValues = signature.split("#"); String memberName = null; ! TypeElement te = null; ! if (sigValues.length == 1) { //Case 2: @value in same class. ! if (utils.isExecutableElement(holder) || utils.isVariableElement(holder)) { ! te = utils.getEnclosingTypeElement(holder); ! } else if (utils.isTypeElement(holder)) { ! te = utils.getTopMostContainingTypeElement(holder); } ! memberName = sigValues[0]; } else { //Case 3: @value in different class. ! Elements elements = config.root.getElementUtils(); ! te = elements.getTypeElement(sigValues[0]); ! memberName = sigValues[1]; } ! if (te == null) { return null; } ! for (Element field : utils.getFields(te)) { ! if (utils.getSimpleName(field).equals(memberName)) { ! return (VariableElement)field; } } return null; } /** * {@inheritDoc} */ ! public Content getTagletOutput(Element holder, DocTree tag, TagletWriter writer) { ! Utils utils = writer.configuration().utils; ! VariableElement field = getVariableElement(holder, writer.configuration(), tag); if (field == null) { ! if (tag.toString().isEmpty()) { //Invalid use of @value ! writer.getMsgRetriever().warning(holder, "doclet.value_tag_invalid_use"); } else { //Reference is unknown. ! writer.getMsgRetriever().warning(holder, ! "doclet.value_tag_invalid_reference", tag.toString()); } ! } else if (field.getConstantValue() != null) { return writer.valueTagOutput(field, ! utils.constantValueExpresion(field), ! // TODO: investigate and cleanup ! // in the j.l.m world, equals will not be accurate ! // !field.equals(tag.holder()) ! !utils.elementsEqual(field, holder) ! ); } else { //Referenced field is not a constant. ! writer.getMsgRetriever().warning(holder, ! "doclet.value_tag_invalid_constant", utils.getSimpleName(field)); } return writer.getOutputInstance(); } }