CODEWITHSUNDEEP
javadocumentation
Martin Pfeffer
Martin Pfeffer

Reputation: 12627

Writing java docs - showing an output example

I'm asking myself how to show an example of an output in java docs. See here...

/**
 * Returns the app's version-info (e.g.: "App 1.2").
 */
public static String getAppVersionInfo() {
    return getAppName() + " " + getVersionName();
}

How to express the 'e.g.' in a convenient way?

Upvotes: 2

Views: 133

Answers (1)

Cinnam
Cinnam

Reputation: 1922

As far as I know, Javadoc doesn't have a special tag for example values.

The closest thing to what you are describing that I remember encountering would be examples of hashing algorithms in MessageDigest#getAlgorithm(). In that case the authors simply say

... The name should be a standard Java Security name (such as "SHA", "MD5", and so on). ...

There is also the Javadoc HowTo, which specifically discourages using "e.g.":

Avoid Latin

use "also known as" instead of "aka", use "that is" or "to be specific" instead of "i.e.", use "for example" instead of "e.g.", and use "in other words" or "namely" instead of "viz."

Other than that, I'm not aware of any rules or best practices applicable to your situation.

Upvotes: 1

Related Questions