javadoc注释中的代码示例

Question

我有多个程序员为javadoc提供示例，一些示例包含使用

格式化的注释

/*
 *
 */

当我将这些示例放入javadoc注释中时，示例中的注释close将关闭javadoc注释。

/**
 *
 * /*
 *  *
 *  */  <-- right here
 *
 */

有没有一种正确的方法来处理这个问题而不告诉每个人他们不能用这种格式写评论？

Answer 1

Javadoc注释使用html，因此将/编码为实体：/

/**
 *
 * /*
 *  *
 *  *&#47;  <-- right here
 *
 */

告诉所有人不要在他们的代码示例中添加这种评论可能会更容易。

Answer 2

在我看来，如果代码不是不言自明的，或者至少很简单，只需要简要描述，那么代码应该被重构。它需要更短，或者变量需要更容易理解，或者逻辑需要重新思考。

在任何情况下，我都不相信有一种解决方法，如果你想包含一个例子，那么在这个例子中没有任何评论。如果确实必须有评论，请使用//表示法。

Answer 3

为什么要将注释的源代码放入评论中？

这听起来像你的设计有问题，如果有必要的话。

Answer 4

在Javadoc评论中允许使用HTML。将评论中的代码包含在<code>或<pre>元素中。例如：

/**
 * Outputs "Hello World" to the console.
 *
 * <code>System.out.println("Hello World");</code>
 */

Answer 5

“/ * * /”注释不能嵌套。 “//”评论可以，但它们只有在他们开始的行结束时才有效。

一般来说，在JavaDocs中包含实际代码并不是一件好事 - 首先，它们应该更抽象（“为什么”而不是“如何”）。