documentation/issue-45: Use inline {@return ...} tag for Javadoc summaries missing from the public API

[philliplbryant]

Closes #45

• Text-only change: no method signatures, behavior, or logic were touched.
• One "Boy Scout" fix: DockBuilding.leaf(String)'s doc had been copy-pasted from branch(String) — corrected while I was already editing.

[Col-E]

Sentence casing changes, and punctuation in most of the classes changed.

[Col-E]

Example I found online:

/**
 * {@return The configuration property value.}
 * If the property does not exist in the system environment, 
 * this method will fallback to checking local properties.
 */
public String getProperty(String key) { ... }

In this case I see why this exists. First sentence becomes the @return.

However if the block is this:

/**
 * {@return The configuration property value.}
 */
public String getProperty(String key) { ... }

Then you just have the same thing twice, once in the summary and once in the @return which doesn't seem useful IMO. All of the changes in this MR are the latter variant which IMO doesn't add any value.

[philliplbryant]

Hi @Col-E ,

In response to your comments, take a look at theJDK 25 source for ZipEntry#getName(), which uses the inline tag:

/**
 * {@return the name of the entry}
 */
public String getName() {
    return name;
}

and compare it to the JavaDocs

Method Summary

Method Details

Notice the Method Summary table row for getName() reads "Returns the name of the entry.", which was generated from the {@return} text. The Method Detail section below repeats the same under Returns:, which is normal JavaDoc styling (summary sentence + @return tag). This is the JDK's reference implementation of the tag, which I used.

So, what's gained by using {@return}?

1. A blank cell in the method summary table gets filled in, providing readers information without having to drill down to find it.
2. More importantly, ignored JavaDoc/doclint warnings get fixed. These changes are meant to eliminate the noise of dozens of warnings now, and eventually stop suppressing JavaDoc warnings altogether, with the ultimate goal of seeing new warnings that might actually matter.

As far as the changes in case and punctuation: fair point, but it's not arbitrary. {@return X} renders as Returns X. — capital "R", then whatever follows has to read as a sentence continuation. {@return Factory for creating...} would render "Returns Factory for creating..." (double-capitalized, reads awkwardly), so the original text got lowercased and de-punctuated to fit grammatically after the auto-prepended "Returns".

It's probably obvious I'm making these changes agentically. I'm happy to continue burning tokens to try to make things "better". If you don't think it's better, let me know.