On Wed, 2 Dec 2020 15:39:56 GMT, Roger Riggs <rri...@openjdk.org> wrote:
>> @RogerRiggs ,
>>
>> 1. I agree on that the lack of `.` after `}` looks unnatural:
>>
>> /**
>> * {@return the result} Optional additional text.
>> */
>> int method() {
>>
>> 2. I disagree on allowing a flexible expansion. This enhancement aims to
>> support a very particular case of redundancy in doc comments. I believe that
>> the proportion of redundant doc comments that use some other verb (instead
>> of "Return(s)") is smaller than it needs to be to support the increase in
>> tag's complexity.
>
> There is lots of other duplication/repetition in most javadoc. I'd rather see
> some kind of text macro that would allow a single definition of a string that
> can be repeated. The source would be a bit less readable, but it would be
> lower maintenance when the same phrase or sentence is repeated to make the
> javadoc more locally complete and easier to read in isolation. Now many times
> do you have to say "throws NullPointerException when the reference is null"
> or similar assertion.
@RogerRiggs,
Here are some more thoughts on flexible expansion (i.e. not forcing a
particular verb). To understand the nature and estimate the prevalence of cases
where "Return(s)" was inappropriate as the first word of an internally
repetitive doc comment, I conducted the following experiment in JDK.
I searched for doc comments whose first sentence was at least 90% similar to
the contents of `@ return` tag. My program ignored differences in markup and
compared contents as strings using normalized Levenshtein similarity; I got
3432 results. Then I modified the program to ignore those doc comments whose
first sentence case-insensitively started with "return"; I got 194 results.
While more analysis might be required, I can preliminary see that we are
talking about 5% of the cases. Which is not much, if you ask me. Here are a few
findings made by the modified program:
/**
* Cleaner for use within system modules.
...
* @return a Cleaner for use within system modules
*/
public static Cleaner cleaner() {
/**
* Get the localization resource bundle
...
* @return the localization resource bundle
*/
public ResourceBundle getResourceBundle() {
/**
* Obtains a line that is available for use and that matches the description
* in the specified {@code Line.Info} object.
...
* @return a line that is available for use and that matches the description
* in the specified {@code Line.Info} object
...
*/
Line getLine(Line.Info info) throws LineUnavailableException;
/**
* The description of this filter. For example: "JPG and GIF Images."
*
* @return the description of this filter
*/
public String getDescription() {
/**
* Fetch the object representing the layout state of
* of the child at the given index.
...
* @return the object representing the layout state of
* of the child at the given index
*/
protected ChildState getChildState(int index) {
/**
* Creates a new instance of the {@code DatatypeFactory} {@linkplain
* #DATATYPEFACTORY_IMPLEMENTATION_CLASS builtin system-default
* implementation}.
*
* @return A new instance of the {@code DatatypeFactory} builtin
* system-default implementation.
...
*/
public static DatatypeFactory newDefaultInstance() {
/**
* True if this iterator has a reversed axis.
*
* @return <code>true</code> if this iterator is a reversed axis.
*/
public boolean isReverse() {
/**
* Check if the annotation contains an array of annotation as a value. This
* check is to verify if a repeatable type annotation is present or not.
...
* @return true if the annotation contains an array of annotation as a value.
*/
private boolean isAnnotationArray(Map<? extends ExecutableElement, ? extends
AnnotationValue> pairs) {
...
The most frequent first word in those 194 results was "Get(s)".
-------------
PR: https://git.openjdk.java.net/jdk/pull/1355
