Java 注释中的/** 和/* [英] /** and /* in Java Comments

问题描述

和

/**
 * comment
 *
 *
 */

和

/*
 * 
 * comment
 *
 */

在Java中?我应该什么时候使用它们?

in Java? When should I use them?

推荐答案

第一种形式称为 Javadoc.当您为您的代码编写正式的 API 时，您可以使用它，这些 API 是由 javadoc 工具生成的.例如，Java 7 API 页面使用 Javadoc 并由该工具生成.

The first form is called Javadoc. You use this when you're writing formal APIs for your code, which are generated by the javadoc tool. For an example, the Java 7 API page uses Javadoc and was generated by that tool.

您会在 Javadoc 中看到的一些常见元素包括:

Some common elements you'd see in Javadoc include:

• @param:这用于指示传递给方法的参数是什么，以及它们应该具有什么值

• @param: this is used to indicate what parameters are being passed to a method, and what value they're expected to have

@return:用于指示该方法将返回什么结果

@return: this is used to indicate what result the method is going to give back

@throws:用于指示某个方法在特定输入的情况下抛出异常或错误

@throws: this is used to indicate that a method throws an exception or error in case of certain input

@since:用于表示该类或函数在

@since: this is used to indicate the earliest Java version this class or function was available in

例如，这里是 Integer 的 compare 方法的 Javadoc:

As an example, here's Javadoc for the compare method of Integer:

/**
 * Compares two {@code int} values numerically.
 * The value returned is identical to what would be returned by:
 * <pre>
 *    Integer.valueOf(x).compareTo(Integer.valueOf(y))
 * </pre>
 *
 * @param  x the first {@code int} to compare
 * @param  y the second {@code int} to compare
 * @return the value {@code 0} if {@code x == y};
 *         a value less than {@code 0} if {@code x < y}; and
 *         a value greater than {@code 0} if {@code x > y}
 * @since 1.7
 */
public static int compare(int x, int y) {
    return (x < y) ? -1 : ((x == y) ? 0 : 1);
}

第二种形式是块(多行)注释.如果您想在注释中包含多行，请使用此选项.

The second form is a block (multi-line) comment. You use this if you want to have multiple lines in a comment.

我会说你只想谨慎地使用后一种形式；也就是说，您不希望使用未描述方法/复杂函数应该具有的行为的块注释使代码负担过重.

I will say that you'd only want to use the latter form sparingly; that is, you don't want to overburden your code with block comments that don't describe what behaviors the method/complex function is supposed to have.

由于 Javadoc 是两者中更具描述性的，并且您可以通过使用它来生成实际文档，因此使用 Javadoc 比简单的块注释更可取.

Since Javadoc is the more descriptive of the two, and you can generate actual documentation as a result of using it, using Javadoc would be more preferable to simple block comments.

这篇关于Java 注释中的/** 和/*的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！