I disagree, the repeat itself is an issue and I show examples of this a bit later in this post.
But we can both remove the repeat, and also improve the javadoc in other ways.
And this proposal/vote is going to be used as an excuse to avoid writing good javadoc
I don’t see how. This doesn’t prevent us writing a good, dedicated description when that’s better. I hope bad descriptions will be usually rejected during reviews.
We have many examples in the XWiki codebase where the description mostly repeats the return and this proposal makes those cases better for people who read and write the code themselves.
One can find a lot of examples by grepping the xwiki-plaftorm code like this:
rg -F "* Get"
rg -F "* Retrieve"
rg -F "* Return"
rg -F "* Generate"
The mere existence of these 4 verbs (and probably more), in their first person or third person form (so 8 ways of doing it) to mean mostly the same thing shows that there are many inconsistencies caused by the absence of this feature.
See for instance xwiki-platform/xwiki-platform-core/xwiki-platform-oldcore/src/main/java/com/xpn/xwiki/web/ExportURLFactory.java at bc64d746c43ad9bb40e966d75e9de5d90aa18de4 · xwiki/xwiki-platform · GitHub :
/**
* Generate an url targeting attachment in provided wiki page.
*
* @param filename the name of the attachment.
* @param spaces a serialized space reference which can contain one or several spaces (e.g. "space1.space2"). If
* a space name contains a dot (".") it must be passed escaped as in "space1\.with\.dot.space2"
* @param name the name of the page containing the attachment.
* @param xwikidb the wiki of the page containing the attachment.
* @param context the XWiki context.
* @return the generated url.
* @throws XWikiException error when retrieving document attachment.
* @throws IOException error when retrieving document attachment.
* @throws URISyntaxException when retrieving document attachment.
*/
Would turn into (with light editing to make it look a bit better - adopting this feature can be the occasion to perform such edits as well):
/**
* {@return a URL targeting the given attachment in the provided wiki page}
*
* @param filename the name of the attachment.
* @param spaces a serialized space reference which can contain one or several spaces (e.g. "space1.space2"). If
* a space name contains a dot (".") it must be passed escaped as in "space1\.with\.dot.space2"
* @param name the name of the page containing the attachment.
* @param xwikidb the wiki of the page containing the attachment.
* @param context the XWiki context.
* @throws XWikiException error when retrieving document attachment.
* @throws IOException error when retrieving document attachment.
* @throws URISyntaxException when retrieving document attachment.
*/
This is of course less repetition when writing and reading the javadoc source. You end up having more details in the generated javadoc at the place the return value is documented with less effort.
Another instance:
/**
* Perform a 3-way merge between the given objects.
*
* @param previousObject the previous object.
* @param newObject the new object.
* @param currentObject the current object.
* @param configuration the configuration for the merge operation.
* @param <T> the type of the object
* @return an obtained merged object.
*/
<T> MergeManagerResult<T, T> mergeObject(T previousObject, T newObject, T currentObject,
MergeConfiguration configuration);
This turns into:
/**
* {@return a 3-way merge between the given objects}
*
* @param previousObject the previous object.
* @param newObject the new object.
* @param currentObject the current object.
* @param configuration the configuration for the merge operation.
* @param <T> the type of the object
*/
<T> MergeManagerResult<T, T> mergeObject(T previousObject, T newObject, T currentObject,
MergeConfiguration configuration);
The original writers must have felt like repeating themselves in the @return tag, so they rephrased the description with fewer details. Beside this unnecessary extra thinking to come up with an alternative phrasing because copy-pasting feels bad, that “returns the obtained merged object” phrasing reads a bit weird.
I’m quite sure the vast majority of cases are like this actually.
There are also at last several – if not many – places where we are already in the situation where the javadoc has no dedicated description but has a @return tag. It’s the case up to the example given in deprecation rules section of the development practices page:
/**
* @param time the time in milliseconds
* @return the time delta in milliseconds between the current date and the time passed as parameter
* @deprecated replaced by {@link com.xpn.xwiki.api.Util#getTimeDelta(long)} since 1.3M2
*/
@Deprecated
public int XWiki.getTimeDelta(long time)
{
return this.util.getTimeDelta(time);
or in the Javadoc Best Practices section itself:
Do not repeat the name of the method or any useless information. For example, if you have:
/**
* @return the id
*/
public String getId()
{
return this.id;
}
Instead, write:
/**
* @return the attachment id (the id is the filename of the XWikiAttachment object used to construct this Attachment object)
*/
public String getId()
{
return this.id;
}
(By the way, this is because of this section, and because I never read XWiki’s generated javadoc, that I thought it was okay to write javadocs without description and that the javadoc processor would do the right thing).
It seems to me adopting that feature would improve these occurrences as well, because suddenly the generated doc will have a description where it must appear.
Coming back to that advice:
Do not repeat the name of the method or any useless information
I know it doesn’t mean the same thing, but it seems that this feature helps with not repeating stuff, which is advised here. It would only make us more consistent with our own advice.
And this proposal/vote is going to be used as an excuse to avoid writing good javadoc, which is now extremely easy with LLMs.
It seems like you are contracting yourself: if it’s very easy with LLMs, why would one use such a mechanism as an excuse to avoid writing good javadoc?
But in reality, I don’t see how the existence of LLMs should have any bearing on the documentation practice. Whether you use them or not to write your doc, the result should ideally be the same (as in, if your LLM generates slop or subtle inaccuracies, that should be fixed before committing to match what a good documentation writer would have written by hand).
For LLM users, that’s also more concise javadocs and thus fewer token spent reading and writing those.
I personally mostly don’t use the generated javadocs unless the IDE happens to display it correctly at the right moment when I navigate the code (but never took the habit of relying on this), so those raw javadoc comments are what I see when I work with the codebase. And they are more verbose than needed. I also don’t use LLMs and don’t intend to, so I care a lot about how the javadoc looks in the code and how easy it is to write.
It seems to me we should trust the javadoc authors for having written and adopted this feature for their own codebase that it leads to better results in many cases, the opposite would be a bit weird. That’s somewhat an appeal to authority, but I’m inclined to believe that they are experts in this stuff and they know what they are doing. Why would they be wrong? I think this feature will help us writing less boilerplate and have more “time” / “cognitive energy” to focus on the rest of the javadoc and write it better.
Do you have examples of places where we risk doing the wrong thing with this new feature?
