Fix grammar in JavaDoc for fully qualified links [SPR-17208]

[spring-projects-issues]

Sam Brannen opened SPR-17208 and commented

Overview

It was brought to our attention in a discussion on GitHub that JavaDoc links created from a fully qualified class name (FQCN) end up as only the simple class name in the generated HTML.

For example, in the JavaDoc for the constructor for JCacheCache, we have the following.

/**
 * Create an {@link org.springframework.cache.jcache.JCacheCache} instance.
 * @param jcache backing JCache Cache instance
 */
public JCacheCache(Cache<Object, Object> jcache) {
	this(jcache, true);
}

The Spring Team has always assumed that the generated HTML would look like the following.

Create an org.springframework.cache.jcache.JCacheCache instance.

In fact, that is what Eclipse IDE generates in the JavaDoc view. The above was literally copied and pasted from Eclipse.

However, the generated HTML on docs.spring.io actually looks like the following.

Create an JCacheCache instance.

This makes the statement grammatically incorrect since JCacheCache starts with a consonant instead of a vowel (i.e., if it were instead org.springframework.cache.jcache.JCacheCache).

Deliverables

1. Determine if there is a flag that instructs JavaDoc to emit the FQCN instead of the simple class name.
2. If there is no such configuration option/flag, devise a means to update all affected JavaDoc within the code base accordingly -- for example, via regular expressions.

---

Affects: 5.1 RC2

Reference URL: #1938 (comment)

Referenced from: commits 2bb15f7, 35c847a

[spring-projects-issues]

Sam Brannen commented

I investigated whether this has always been the case in our generated HTML, and it in fact is the case all the way back to Spring 3.2.0.

https://docs.spring.io/spring/docs/3.2.0.RELEASE/javadoc-api/org/springframework/cache/jcache/JCacheCache.html#JCacheCache(javax.cache.Cache)

[spring-projects-issues]

Sam Brannen commented

It is apparently possible to remove all package names globally via the -noqualifier command-line option.

However, after a fair amount of research I have yet to find a way to always include the package name.

[spring-projects-issues]

Sam Brannen commented

The documentation for the javadoc tool explicitly states the following for both the @see and @link tags.

How a Name Appears

If label is omitted, then package.class.member appears. In general, it is suitably shortened relative to the current class and package. Shortened means the javadoc command displays only the minimum name necessary. For example, if the String.toUpperCase() method contains references to a member of the same class and to a member of a different class, then the class name is displayed only in the latter case, as shown in the following listing. Use the -noqualifier option to globally remove the package names.

[spring-projects-issues]

Sam Brannen commented

In summary, as far as I can tell, there is no way to have the javadoc tool include the fully qualified class name for the current class or classes within the same package.... unless you explicitly specify a custom label.

Thus, in order to force the JavaDoc for the JCacheCache constructor to include the fully qualified class name, we would have to compose the link as:

/**
 * Create an {@link org.springframework.cache.jcache.JCacheCache
 * org.springframework.cache.jcache.JCacheCache} instance.
 */

or:

/**
 * Create an {@link JCacheCache org.springframework.cache.jcache.JCacheCache}
 * instance.
 */

[spring-projects-issues]

Sam Brannen commented

Grammatical violations of the "a" vs. "an" rule have been addressed (using a best effort approach) in the following commits. Note, however, that there still may be various places in the JavaDoc that violate the rule that were not revealed by the searches I used.

• 35c847a
• 2bb15f7