java - 如何记录带有变体的代码？ (用于 ifs 的 JavaDoc)

Question

tl;dr if 是否有 JavaDoc？

简介

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

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

我现在想为用户记录所有这些变体。从文档中应该清楚如果我打开例如会发生什么。模块 REPORTS。我认为该文档应该以 JavaDoc 方式编写——这意味着它应该尽可能接近条件代码。它可能看起来像这样:

/** 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 测试期间收集文档，然后将其构建到最终版本中。缺点很明显:如果系统的某个部分未被访问，则不会被记录下来。

字节码提取

为了避免乱七八糟的源代码，人们只能找到编译后的字节码，用 ASM 之类的东西对其进行分析。并找到所有调用 user.hasModule() 的地方。这是我最喜欢的版本，但卡住了 以及如何确定调用 invoke_static 时 VM 堆栈顶部的实际值。必须有一个更简单的方法:)

总结

有工具吗？我是否缺少一种简单的方法来做到这一点？我在尝试记录此类情况时是否完全被误导了？谢谢!

Answer 1

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

您的模块看起来很像安全组，每次使用看起来很像权限。

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

下面的方案使用 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
  }

这很可能是矫枉过正 - 一个没有所有自输入废话的简单枚举可能就足够了。

if user.hasPermission(Permissions.Export)