jdk8-mips64-public/langtools: comparison src/share/classes/com/sun/tools/doclets/internal/toolkit/util/DocFinder.java

--1:000000000000
+:959103a6100f
+/*
+* Copyright (c) 2003, 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
+* particular file as subject to the "Classpath" exception as provided
+* by Oracle in the LICENSE file that accompanied this code.
+*
+* This code is distributed in the hope that it will be useful, but WITHOUT
+* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+* FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+* version 2 for more details (a copy is included in the LICENSE file that
+* accompanied this code).
+*
+* You should have received a copy of the GNU General Public License version
+* 2 along with this work; if not, write to the Free Software Foundation,
+* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+*
+* 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.util;
+import java.util.*;
+import com.sun.javadoc.*;
+import com.sun.tools.doclets.internal.toolkit.taglets.*;
+/**
+* Search for the requested documentation.  Inherit documentation if necessary.
+*
+*  <p><b>This is NOT part of any supported API.
+*  If you write code that depends on this, you do so at your own risk.
+*  This code and its internal interfaces are subject to change or
+*  deletion without notice.</b>
+*
+* @author Jamie Ho
+* @since 1.5
+*/
+public class DocFinder {
+/**
+* The class that encapsulates the input.
+*/
+public static class Input {
+/**
+* The element to search documentation from.
+*/
+public ProgramElementDoc element;
+/**
+* The taglet to search for documentation on behalf of. Null if we want
+* to search for overall documentation.
+*/
+public InheritableTaglet taglet = null;
+/**
+* The id of the tag to retrieve documentation for.
+*/
+public String tagId = null;
+/**
+* The tag to retrieve documentation for.  This is only used for the
+* inheritDoc tag.
+*/
+public Tag tag = null;
+/**
+* True if we only want to search for the first sentence.
+*/
+public boolean isFirstSentence = false;
+/**
+* True if we are looking for documentation to replace the inheritDocTag.
+*/
+public boolean isInheritDocTag = false;
+/**
+* Used to distinguish between type variable param tags and regular
+* param tags.
+*/
+public boolean isTypeVariableParamTag = false;
+public Input(ProgramElementDoc element, InheritableTaglet taglet, Tag tag,
+boolean isFirstSentence, boolean isInheritDocTag) {
+this(element);
+this.taglet = taglet;
+this.tag = tag;
+this.isFirstSentence = isFirstSentence;
+this.isInheritDocTag = isInheritDocTag;
+}
+public Input(ProgramElementDoc element, InheritableTaglet taglet, String tagId) {
+this(element);
+this.taglet = taglet;
+this.tagId = tagId;
+}
+public Input(ProgramElementDoc element, InheritableTaglet taglet, String tagId,
+boolean isTypeVariableParamTag) {
+this(element);
+this.taglet = taglet;
+this.tagId = tagId;
+this.isTypeVariableParamTag = isTypeVariableParamTag;
+}
+public Input(ProgramElementDoc element, InheritableTaglet taglet) {
+this(element);
+this.taglet = taglet;
+}
+public Input(ProgramElementDoc element) {
+if (element == null)
+throw new NullPointerException();
+this.element = element;
+}
+public Input(ProgramElementDoc element, boolean isFirstSentence) {
+this(element);
+this.isFirstSentence = isFirstSentence;
+}
+public Input copy() {
+Input clone = new Input(this.element);
+clone.taglet = this.taglet;
+clone.tagId = this.tagId;
+clone.tag = this.tag;
+clone.isFirstSentence = this.isFirstSentence;
+clone.isInheritDocTag = this.isInheritDocTag;
+clone.isTypeVariableParamTag = this.isTypeVariableParamTag;
+if (clone.element == null)
+throw new NullPointerException();
+return clone;
+}
+}
+/**
+* The class that encapsulates the output.
+*/
+public static class Output {
+/**
+* The tag that holds the documentation.  Null if documentation
+* is not held by a tag.
+*/
+public Tag holderTag;
+/**
+* The Doc object that holds the documentation.
+*/
+public Doc holder;
+/**
+* The inherited documentation.
+*/
+public Tag[] inlineTags = new Tag[] {};
+/**
+* False if documentation could not be inherited.
+*/
+public boolean isValidInheritDocTag = true;
+/**
+* When automatically inheriting throws tags, you sometime must inherit
+* more than one tag.  For example if the element declares that it throws
+* IOException and the overridden element has throws tags for IOException and
+* ZipException, both tags would be inherited because ZipException is a
+* subclass of IOException.  This subclass of DocFinder.Output allows
+* multiple tag inheritence.
+*/
+public List<Tag> tagList  = new ArrayList<Tag>();
+}
+/**
+* Search for the requested comments in the given element.  If it does not
+* have comments, return documentation from the overriden element if possible.
+* If the overriden element does not exist or does not have documentation to
+* inherit, search for documentation to inherit from implemented methods.
+*
+* @param input the input object used to perform the search.
+*
+* @return an Output object representing the documentation that was found.
+*/
+public static Output search(Input input) {
+Output output = new Output();
+if (input.isInheritDocTag) {
+//Do nothing because "element" does not have any documentation.
+//All it has it {@inheritDoc}.
+} else if (input.taglet == null) {
+//We want overall documentation.
+output.inlineTags = input.isFirstSentence ?
+input.element.firstSentenceTags() :
+input.element.inlineTags();
+output.holder = input.element;
+} else {
+input.taglet.inherit(input, output);
+}
+if (output.inlineTags != null && output.inlineTags.length > 0) {
+return output;
+}
+output.isValidInheritDocTag = false;
+Input inheritedSearchInput = input.copy();
+inheritedSearchInput.isInheritDocTag = false;
+if (input.element instanceof MethodDoc) {
+MethodDoc overriddenMethod = ((MethodDoc) input.element).overriddenMethod();
+if (overriddenMethod != null) {
+inheritedSearchInput.element = overriddenMethod;
+output = search(inheritedSearchInput);
+output.isValidInheritDocTag = true;
+if (output.inlineTags.length > 0) {
+return output;
+}
+}
+//NOTE:  When we fix the bug where ClassDoc.interfaceTypes() does
+//       not pass all implemented interfaces, we will use the
+//       appropriate element here.
+MethodDoc[] implementedMethods =
+(new ImplementedMethods((MethodDoc) input.element, null)).build(false);
+for (int i = 0; i < implementedMethods.length; i++) {
+inheritedSearchInput.element = implementedMethods[i];
+output = search(inheritedSearchInput);
+output.isValidInheritDocTag = true;
+if (output.inlineTags.length > 0) {
+return output;
+}
+}
+} else if (input.element instanceof ClassDoc) {
+ProgramElementDoc superclass = ((ClassDoc) input.element).superclass();
+if (superclass != null) {
+inheritedSearchInput.element = superclass;
+output = search(inheritedSearchInput);
+output.isValidInheritDocTag = true;
+if (output.inlineTags.length > 0) {
+return output;
+}
+}
+}
+return output;
+}
+}

Mercurial > jdk8-mips64-public > langtools / file comparison

comparison: src/share/classes/com/sun/tools/doclets/internal/toolkit/util/DocFinder.java

src/share/classes/com/sun/tools/doclets/internal/toolkit/util/DocFinder.java