java - 编写 Java 文档 - 显示输出示例

Question

我在问自己如何在 Java 文档中显示输出示例。看这里...

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

如何表达“例如”以方便的方式？

Answer 1

据我所知，Javadoc 没有用于示例值的特殊标记。

我记得遇到过的与您所描述的最接近的是 MessageDigest#getAlgorithm() 中的散列算法示例。 .在那种情况下，作者只是说

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

还有 Javadoc HowTo ，特别不鼓励使用“例如”:

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."

除此之外，我不知道适用于您情况的任何规则或最佳做法。