About clarity and javadoc

Question

Opinions divided on this one ...

Guys, say you have a method defined as

public static String getTestName(JsonElement e) throws ParserException;

As a wanna-do-the-the-right-thing developer I'd like to document this appropriately. Original thought was to say:

"Returns String representation of a Test name"

"Or really? It returns String? I see this from the method signature, you know. No need to say it again, just say:

"Returns Test name"

So which one is it? Is there any value in adding "String representation of .." Does it add clarity or noise?

I report you decide.

Thanks

Answer 1

I would put the "String" in there for clarity's sake. In fact, I would consider making the wording more like "human-readable String" (if it is designed to be human-readable), or otherwise describe the formatting of the String if it is designed to be parsed or interpreted by other software.

The best way would be to think of the next developer to use this API or work on this code. For users of an API, they should be able to get all of the information that they need without looking at the code. For developers, they should be able to read the documentation (both in-code, generated, and other external documentation) and have a good understanding of the system. Achieve both of these goals as appropriate.