相关疑难解决方法(0)

当我有一个带注释的代码示例时,我的JavaDoc不起作用.

有什么建议？

/**
 * <pre>
 * public class Demo {
 *    @DemoAnnotation
 *    public void demoMethod() {
 *    }
 * }
 * </pre>
 */ 
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD})
public @interface DemoAnnotation {

我尝试在Oracle文档中搜索 @code java注释的功能.

从前一个问题开始,我意识到它与html有关,但我不确定究竟是什么......

说默认情况下javadoc被解析为HTML是否正确...但是将@code注释放在一些javadoc文本旁边会表明它应该被视为代码,而不是以通常的方式解析/呈现？例如:

    /**
    *This is how to declare an int variable {@code int var=1;}
    */

这是一个适当的使用例子吗？

如何在Kotlin的默认文档工具KDoc中插入代码片段？

在Java中,我可以使用以下内容:

/**
 * Example usage:
 *
 * <pre>
 * <code>&#64;JavaAnnotation
 * public void foo() {
 *     // Code
 * }
 * </code>
 * </pre>
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface JavaAnnotation {}

Kotlin似乎没有相应的东西.我尝试使用Markdown,但在行结束后插入2个空格不会换行.

目前我使用PRE标签在我的javadoc中格式化代码示例,例如:

/**
 * Example javadoc
 * 
<pre>
String foo = "bar";
</pre>
 *
 * @return   true if the operation completed
 */

但是在生成的javadoc中,这看起来相当单调乏味,我宁愿有一些类似于SyntaxHighlighter的语法高亮.

如何才能做到这一点？

我正在尝试使用Netbeans 8.0在Javadoc注释中插入{@code}注释,但它无法正常工作.

我之前已经看过其他问题了(也就是说,你怎么能逃脱javadoc中的@字符？)但是html转义@并且{@literal @}两者似乎都不起作用.

我的评论看起来像这样(为了示例,使用两种方法):

/**
 * blah blah blah
 * <p>
 * For example:
 * <pre>
 * {@code
 * {@literal @}begin_specification
 *  ...
 * &#64;end_specification
 * }
 * </pre>
 */

我可以点击Run -> Generate Javadoc,一切运行正常,没有错误,但是当我在浏览器中查看结果输出时,我看到了这一点:

{@literal @}begin_specification
 ...
@end_specification

哪个不是理想的结果......有什么建议/想法吗？

我是Java的新手,但在过去使用过像C/C++这样的东西.我在这里做错了吗？我正在使用带有Java 1.8.0_05 x64的NetBeans 8.0(Build 201403101706).

我找不到任何关于在javadoc参数中是否可以有多行信息的信息.我正在制作一个国际象棋引擎,我希望能够解析一个字符串来生成一个棋盘.可以这样做,就像我在下面做的那样吗？

/**
 * Creates a board based on a string.
 * @param boardString The string to be parsed. Must be of the format:
 *      "8x8\n" +
 *      "br,bn,bb,bq,bk,bb,bn,br\n" +
 *      "bp,bp,bp,bp,bp,bp,bp,bp\n" +
 *      "  ,  ,  ,  ,  ,  ,  ,  \n" +
 *      "  ,  ,  ,  ,  ,  ,  ,  \n" +
 *      "  ,  ,  ,  ,  ,  ,  ,  \n" +
 *      "  ,  ,  ,  ,  ,  ,  ,  \n" +
 *      "wp,wp,wp,wp,wp,wp,wp,wp\n" +
 * …

我正在开发一个用Java编写的项目,旨在通过一个严格定义消息字段位位置的消息系统来传输数据.这意味着我们有一个完整的字典类库,旨在将对象输入数据移位到消息二进制表示或从消息二进制表示移位.这个库相当大,并且因为协议还很年轻,所以每年都有调整和改变的倾向.

此库的JavaDoc提供了ASCII艺术表和图表,用于解释特定方法期望作为输入(或输出)的内容.这些表格非常重要,因为查找文档并验证该方法实际上是否符合文档所说的内容可能非常耗时,容易出错.使用单个简单的ASCII位表示位移使得这更容易.

我有一个同事坚持认为ASCII艺术不属于JavaDoc(即使是标签),而且我们配置Eclipse以自动格式化保存代码.他提供了两种重新格式化文档的选项:

1. 嵌入图像.
2. 使用HTML表格.

除了Eclipse不渲染SVG图像外,图像没问题.我完全不能接受的是,我们维护一个SVG图像,然后将图像作为PNG导出到我们的文档仓库,然后将PNG与HTML链接起来.这种情况下涉及的维护量似乎完全疯了.谁负责确保所有PNG,SVG和代码同步？此外,显然,没有图像,数据将无法读取.

HTML表选项很糟糕,原因有两个.首先,Eclipse格式化程序将每个标记和值放在它自己的行上,这意味着每个值都占用三行.它在源代码中留下了巨大的空白,并且在不呈现HTML的情况下完全不可读.更糟糕的是,我们的一些表格很复杂,并且对HTML表格进行故障诊断并不是我对负责任的事情的想法,而是要求已经拒绝创建文档的开发人员.

因此,如果我的同事关于"java人"不使用ASCII图表进行文档化,那么什么是标准的行业实践,为我们提供了保存这些图表的方法？与使用ASCII图标签相比,这种方法有何益处？如果你能回答为什么JavaDoc没有发展为提供可读标记而不依赖于HTML,那么奖励点.

编辑:我刚发现markdown-doclet.我不知道这是否是一个可以接受的妥协.也许还有其他类似的工具？

这是我写的 javadoc 注释：

  /**
   * This utility allows the user to do the following.
   * <ul>
   *   <li>A cool feature</li>
   *   <li>Another cool feature</li>
   * </ul>
   */
  public static void main(String[] args) {

这是相同的评论，由 IntelliJ 重新格式化

  /**
   * This utility allows the user to do the following.
   * <ul>
   * <li>A cool feature</li>
   * <li>Another cool feature</li>
   * </ul>
   */
  public static void main(String[] args) {

如何防止自动套用格式功能破坏我的意图？

为了防止 IntelliJ 删除我的换行符，我选中了一个复选框：

设置 > 编辑器 > 代码样式 > Java > JavaDoc > …