如何使用变体记录代码？（国际单项体育联合会的JavaDoc）

tl；dr是否有适用于

if

s的JavaDoc

简介 我正在为多个客户编写一个企业应用程序。99%的代码库是共享的，但偶尔会有这样的变体：

if (user.hasModule(REPORTS)) { 
  ...conditional code... 
}

/** Enables the cool report. */
if (user.hasModule(REPORTS)) { 
  ...conditional code... 
}

我现在想为用户记录所有这些变体。从文档中应该可以清楚地看到，如果打开模块

报告

，会发生什么情况。我相信这个文档应该以JavaDoc的方式编写——这意味着它应该尽可能接近条件代码。它可能是这样的：

if (user.hasModule(REPORTS)) { 
  ...conditional code... 
}

/** Enables the cool report. */
if (user.hasModule(REPORTS)) { 
  ...conditional code... 
}

或者这个：

@Doc(text="Enables the cool report.")
if (user.hasModule(REPORTS)) { 
  ...conditional code... 
}

或许是这样：

if (user.hasModule(REPORTS, "Enables the cool report.")) { 
  ...conditional code... 
}

结果基本上是每个模块的评论列表

Module    | Comments
----------+--------------------
REPORTS   | Enables the cool report.
REPORTS   | Allows exporting the reports.
IMPORT    | Allows importing the data.

问题: 如何从代码中收集所有文档注释？我正在考虑几种方法：

源代码提取 这需要解析器遍历源代码，找到所有这些条件并获取对（模块、注释）。但是，它必须被钩住到编译器中，以避免奇怪的格式化（长线中间的换行等）的问题。

动态提取 无论何时在运行时调用

user.hasModule（）

，它都会记录其实际参数，然后使用此日志构建文档。例如，在beta测试期间，收集文档，然后将其构建到最终版本中。缺点很明显：如果系统的某个部分没有被访问，它将不会被记录

字节码提取 为了避免混乱的源代码，只需找到编译的字节码，用类似的方法分析它，并找到调用

user.hasModule（）

的所有位置。这是我最喜欢的版本，但被卡住了 如何计算在调用

invoke\u static

时VM堆栈顶部的实际值。必须有一个更简单的方法：）

总结

---

有这个工具吗？我错过了一个简单的方法吗？我试图记录这些条件是否完全被误导了？谢谢

我认为您的代码中缺少了一个概念

您的模块看起来非常像安全组，每次使用都非常像权限

如果您要以这种方式建模，您可以将每个模块的用法/权限的知识集中到一个位置。这样就不需要通过静态分析扫描代码了

下面的方案使用Java类型系统来确保在没有为模块创建新权限的情况下不能为模块添加if语句

从这段代码中可以很容易地生成一个完整的权限和描述列表，只需在枚举值之间进行一点java循环

public interface User {
 public <T extends Module<T>> boolean hasPermission(Module<T> module, Permission<T> usage);
 }

public interface Permission<T extends Module<T>> {
  String describe();
}

enum Reports implements Module<Reports> {
  REPORTS
}

enum ReportsPermissions implements Permission<Reports> {
   ENABLE_COOL_REPORT("Enables the cools reports"),
   ALLOWS_EXPORTING_THE_REPORTS("Allow exports the cools reports");

   private final String description;

    ReportsPermissions(String description) {
      this.description = description;
    }

    @Override
    public String describe() {
      return description;
     } 
  }

  enum ImportPermissions implements Permission<Import> {
    ALLOWS_IMPORTING("Allows importing the data.");
    etc
  }

公共界面用户{
公共权限（模块、权限使用）；
}
公共接口权限{
字符串descripe（）；
}
枚举报表实现模块{
报告
}
enum ReportsPermissions实现权限{
启用冷却报告（“启用冷却报告”），
允许导出报告（“允许导出冷却报告”）；
私有最终字符串描述；
ReportsPermissions（字符串描述）{
this.description=描述；
}
@凌驾
公共字符串descripe（）{
返回说明；
} 
}
enum ImportPermissions实现权限{
允许导入（“允许导入数据”）；
等
}

这很可能是过分的——一个简单的枚举，没有所有的自类型错误，可能就足够了

---

如果user.hasPermission（Permissions.Export）

我会将

user.hasModule（REPORTS）==true时执行的代码放入一个。然后用JavaDoc记录这个方面。
我不明白你想做什么。是否要为其他开发人员记录
if
中发生的事情？或者，根据启用的模块，是否希望在运行时为用户生成文档？对我来说这听起来有点奇怪。后者是用户的文档。那么Javadoc不是你选择的工具。它用于记录代码，而不是供用户阅读。这是一种技术手段。而且JavaDoc绝对不能像ifs

那样记录代码结构，所以我要找的不是JavaDoc，而是类似的东西。我仍然不明白为什么要为用户记录代码结构。他对代码中发生的事情不感兴趣，他想知道软件是如何工作的。这正是模块定义现在的工作方式。我称之为模块，因为也有权限，是的，问题也与它们有关。然而，我们正试图记录所有的ifs-想象一下有100个ifs使用每个枚举值！我的观点是，每个“如果”都必须与一些可观察的功能相关。您应该为该功能创建一个模型-目前模块概念没有捕捉到这一点，您需要更深入一步。因此，您基本上有一个所有ifs的枚举？实际上，假设它不会是1:1，因为一个可观察的功能可能需要多个位置的分支，但是，是的，创建if语句试图实现的目标的模型，并将其记录下来。