# HG changeset patch # User darcy # Date 1255571797 25200 # Node ID 2b391dcb03ff996be4841b26fa9e9f34b0c369c9 # Parent 9788f4549740b4d7783e47bdc9fdd199b94fce58 6558804: Specification for Elements.getDocComment(Element e) should be clarified Reviewed-by: jjg diff -r 9788f4549740 -r 2b391dcb03ff langtools/src/share/classes/javax/lang/model/util/Elements.java --- a/langtools/src/share/classes/javax/lang/model/util/Elements.java Wed Oct 14 15:41:28 2009 -0700 +++ b/langtools/src/share/classes/javax/lang/model/util/Elements.java Wed Oct 14 18:56:37 2009 -0700 @@ -77,9 +77,25 @@ * Returns the text of the documentation ("Javadoc") * comment of an element. * + *
A documentation comment of an element is a comment that
+ * begins with "{@code /**}" , ends with a separate
+ * "*/
", and immediately precedes the element,
+ * ignoring white space. Therefore, a documentation comment
+ * contains at least three"{@code *}" characters. The text
+ * returned for the documentation comment is a processed form of
+ * the comment as it appears in source code. The leading "{@code
+ * /**}" and trailing "*/
" are removed. For lines
+ * of the comment starting after the initial "{@code /**}",
+ * leading white space characters are discarded as are any
+ * consecutive "{@code *}" characters appearing after the white
+ * space or starting the line. The processed lines are then
+ * concatenated together (including line terminators) and
+ * returned.
+ *
* @param e the element being examined
* @return the documentation comment of the element, or {@code null}
* if there is none
+ * @jls3 3.6 White Space
*/
String getDocComment(Element e);