1.1 --- a/src/share/classes/com/sun/tools/doclets/internal/toolkit/builders/MemberSummaryBuilder.java Fri Feb 22 18:19:51 2013 +0000
1.2 +++ b/src/share/classes/com/sun/tools/doclets/internal/toolkit/builders/MemberSummaryBuilder.java Sun Feb 24 11:36:58 2013 -0800
1.3 @@ -1,5 +1,5 @@
1.4 /*
1.5 - * Copyright (c) 2003, 2012, Oracle and/or its affiliates. All rights reserved.
1.6 + * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved.
1.7 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.8 *
1.9 * This code is free software; you can redistribute it and/or modify it
1.10 @@ -26,6 +26,7 @@
1.11 package com.sun.tools.doclets.internal.toolkit.builders;
1.12
1.13 import java.util.*;
1.14 +import java.text.MessageFormat;
1.15
1.16 import com.sun.javadoc.*;
1.17 import com.sun.tools.doclets.internal.toolkit.*;
1.18 @@ -82,7 +83,7 @@
1.19 new VisibleMemberMap(
1.20 classDoc,
1.21 i,
1.22 - configuration.nodeprecated);
1.23 + configuration);
1.24 }
1.25 }
1.26
1.27 @@ -254,6 +255,17 @@
1.28 }
1.29
1.30 /**
1.31 + * Build the summary for the fields.
1.32 + */
1.33 + public void buildPropertiesSummary(XMLNode node, Content memberSummaryTree) {
1.34 + MemberSummaryWriter writer =
1.35 + memberSummaryWriters[VisibleMemberMap.PROPERTIES];
1.36 + VisibleMemberMap visibleMemberMap =
1.37 + visibleMemberMaps[VisibleMemberMap.PROPERTIES];
1.38 + addSummary(writer, visibleMemberMap, true, memberSummaryTree);
1.39 + }
1.40 +
1.41 + /**
1.42 * Build the summary for the nested classes.
1.43 *
1.44 * @param node the XML element that specifies which components to document
1.45 @@ -311,6 +323,11 @@
1.46 List<Content> tableContents = new LinkedList<Content>();
1.47 for (int i = 0; i < members.size(); i++) {
1.48 ProgramElementDoc member = members.get(i);
1.49 + final ProgramElementDoc propertyDoc =
1.50 + visibleMemberMap.getPropertyMemberDoc(member);
1.51 + if (propertyDoc != null) {
1.52 + processProperty(visibleMemberMap, member, propertyDoc);
1.53 + }
1.54 Tag[] firstSentenceTags = member.firstSentenceTags();
1.55 if (member instanceof MethodDoc && firstSentenceTags.length == 0) {
1.56 //Inherit comments from overriden or implemented method if
1.57 @@ -330,6 +347,106 @@
1.58 }
1.59
1.60 /**
1.61 + * Process the property method, property setter and/or property getter
1.62 + * comment text so that it contains the documentation from
1.63 + * the property field. The method adds the leading sentence,
1.64 + * copied documentation including the defaultValue tag and
1.65 + * the see tags if the appropriate property getter and setter are
1.66 + * available.
1.67 + *
1.68 + * @param visibleMemberMap the members information.
1.69 + * @param member the member which is to be augmented.
1.70 + * @param propertyDoc the original property documentation.
1.71 + */
1.72 + private void processProperty(VisibleMemberMap visibleMemberMap,
1.73 + ProgramElementDoc member,
1.74 + ProgramElementDoc propertyDoc) {
1.75 + StringBuilder commentTextBuilder = new StringBuilder();
1.76 + final boolean isSetter = isSetter(member);
1.77 + final boolean isGetter = isGetter(member);
1.78 + if (isGetter || isSetter) {
1.79 + //add "[GS]ets the value of the property PROPERTY_NAME."
1.80 + if (isSetter) {
1.81 + commentTextBuilder.append(
1.82 + MessageFormat.format(
1.83 + configuration.getText("doclet.PropertySetterWithName"),
1.84 + Util.propertyNameFromMethodName(member.name())));
1.85 + }
1.86 + if (isGetter) {
1.87 + commentTextBuilder.append(
1.88 + MessageFormat.format(
1.89 + configuration.getText("doclet.PropertyGetterWithName"),
1.90 + Util.propertyNameFromMethodName(member.name())));
1.91 + }
1.92 + if (propertyDoc.commentText() != null
1.93 + && !propertyDoc.commentText().isEmpty()) {
1.94 + commentTextBuilder.append(" \n @propertyDescription ");
1.95 + }
1.96 + }
1.97 + commentTextBuilder.append(propertyDoc.commentText());
1.98 +
1.99 + Tag[] tags = propertyDoc.tags("@defaultValue");
1.100 + if (tags != null) {
1.101 + for (Tag tag: tags) {
1.102 + commentTextBuilder.append("\n")
1.103 + .append(tag.name())
1.104 + .append(" ")
1.105 + .append(tag.text());
1.106 + }
1.107 + }
1.108 +
1.109 + //add @see tags
1.110 + if (!isGetter && !isSetter) {
1.111 + MethodDoc getter = (MethodDoc) visibleMemberMap.getGetterForProperty(member);
1.112 + MethodDoc setter = (MethodDoc) visibleMemberMap.getSetterForProperty(member);
1.113 +
1.114 + if ((null != getter)
1.115 + && (commentTextBuilder.indexOf("@see #" + getter.name()) == -1)) {
1.116 + commentTextBuilder.append("\n @see #")
1.117 + .append(getter.name())
1.118 + .append("() ");
1.119 + }
1.120 +
1.121 + if ((null != setter)
1.122 + && (commentTextBuilder.indexOf("@see #" + setter.name()) == -1)) {
1.123 + String typeName = setter.parameters()[0].typeName();
1.124 + // Removal of type parameters and package information.
1.125 + typeName = typeName.split("<")[0];
1.126 + if (typeName.contains(".")) {
1.127 + typeName = typeName.substring(typeName.lastIndexOf(".") + 1);
1.128 + }
1.129 + commentTextBuilder.append("\n @see #").append(setter.name());
1.130 +
1.131 + if (setter.parameters()[0].type().asTypeVariable() == null) {
1.132 + commentTextBuilder.append("(").append(typeName).append(")");
1.133 + }
1.134 + commentTextBuilder.append(" \n");
1.135 + }
1.136 + }
1.137 + member.setRawCommentText(commentTextBuilder.toString());
1.138 + }
1.139 + /**
1.140 + * Test whether the method is a getter.
1.141 + * @param ped property method documentation. Needs to be either property
1.142 + * method, property getter, or property setter.
1.143 + * @return true if the given documentation belongs to a getter.
1.144 + */
1.145 + private boolean isGetter(ProgramElementDoc ped) {
1.146 + final String pedName = ped.name();
1.147 + return pedName.startsWith("get") || pedName.startsWith("is");
1.148 + }
1.149 +
1.150 + /**
1.151 + * Test whether the method is a setter.
1.152 + * @param ped property method documentation. Needs to be either property
1.153 + * method, property getter, or property setter.
1.154 + * @return true if the given documentation belongs to a setter.
1.155 + */
1.156 + private boolean isSetter(ProgramElementDoc ped) {
1.157 + return ped.name().startsWith("set");
1.158 + }
1.159 +
1.160 + /**
1.161 * Build the inherited member summary for the given methods.
1.162 *
1.163 * @param writer the writer for this member summary.
