在文档中显示部分方法体答案

【问题标题】：Show part of method body in documentation在文档中显示部分方法体
【发布时间】：2019-09-01 02:33:27
【问题描述】：

我想在其文档 (JavaDoc) 中显示部分方法体。

例如：

/**
 * The algorithm contains steps:
 * @showMethodBody
 */
public void algorithmX(int coordinateX) {
    makeStep1();
    if (coordinateX == TOP) {
        makeStep2();
    }
}

应该生成如下文档：

该算法包含步骤： makeStep1(); 如果（坐标X == TOP）{ makeStep2(); }

我知道这样的文档有点傻，而且不是自然语言。但最好的一点是它永远不会过时。

所以一般概念可以用自然语言描述，但关键元素可以直接从源代码中复制。如您所见，源代码也可以为非程序员提供信息。这是我的问题：

问题：

如何在方法的文档中复制（显示）部分或整个方法体？

现在我正在使用 JavaDoc，但我也可以使用任何其他工具。如果有帮助，我还可以在源代码中添加一些指针（注释或特殊 cmets）。

【问题讨论】：

您为什么要这样做？像方法是一个黑盒子一样编写您的 JavaDocs：输入这些输入，神奇发生，然后输出这个输出。如何一组输入变成输出应该与读者无关，如果他们真的感兴趣，他们可以阅读源代码。
@JonK 因为我们的用户想要包含业务细节的文档——所以我需要公开一些关于我的代码行为的细节。当然，我可以使用自然语言来描述这一点：Algorithm do step1 and step2 if coordinateX is equal to TOP 或者我可以将真实代码放入文档中。

标签： java documentation javadoc doxygen doclet

【解决方案1】：

在 doxygen 中有几种可能性：

INLINE_SOURCES，这里的缺点是所有函数都会包含所有代码
命令dontinclude，与\skip、\line 等一起包含文件的一部分。
\snippet 命令标记代码的某些部分并可以将它们放在文档中

另请参阅http://www.doxygen.nl/manual/ 的 doxygen 手册，在这种情况下，请参阅“特殊命令”和“配置”章节

【讨论】：