7

我正在编写一个库,它将已经单元测试的示例代码(它的源代码、输出和任何输入文件)插入到 JavaDoc 中,具有很多定制的可能性。使用这个库的主要方式是使用内联 taglets,例如

{@.codelet.and.out my.package.AGreatExample}
{@.codelet my.package.AGreatExample}
{@.file.textlet examples\doc-files\an_input_file.txt}
{@.codelet.and.out my.package.AGreatExample%eliminateCommentBlocksAndPackageDecl()}

由于自定义taglets(甚至doclets)需要com.sun,这意味着它们不像 Java 本身那样跨平台。(不确定这是否相关,但“javadoc”这个词——甚至是子字符串“doc”——不在Java 8 语言规范中。)

我不喜欢以这种方式编写一个受限的库的想法。那我该怎么办?到目前为止我的想法是

  • 为了利用现有的 javadoc 解析器,我坚持使用com.suntaglets。com.sun但是,我尽可能地“瘦”这种依赖。也就是说,我将尽可能少的代码放在 taglet 类中,将大部分代码留在不依赖com.sun.
  • 我致力于创建自己的解析器,它只搜索我的特定 taglets。这是一种痛苦,但并不可怕。您遍历每个 Java 源文件的行,搜索\{@\.myTagletName (.*?)\}. 捕获该文本后,它与com.suntaglet 中的代码几乎相同。
  • 这个解析器必须在执行 javadoc 之前运行,因此需要一个重复的目录结构。(1) 您的原始代码,带有未解析的自定义标签,(2) 该代码的副本,带有解析的输出。我将所有代码复制到重复目录,然后仅解析那些已知具有这些标记的 Java 文件(以某种方式使用解析器“注册”的类)。

这是一个合理的方法吗?是否已经有更多的跨平台 javadoc/taglet 解析器,所以我不必自己动手?有没有什么跨平台的东西已经存在了?JavaDoc本身不是跨平台的,还是只是自定义的 taglet 和 doclet?

由于这个决定(使用内联标签),我想大致了解有多少人被锁定在我的图书馆之外,但主要是我正在寻找一个长期的解决方案。

(尽管上面有我的 Java 8 链接,但我使用的是 Java 7。)


感谢 @fge 提出的 taglet 建议,这比我最初的想法更优雅,感谢 @Michael 提供不祥但有用的com.sun警告。

4

1 回答 1

2

首先,请注意sun.*com.sun.*依赖关系之间存在差异。sun.* 命名空间包含实现 Oracle 的 Java 虚拟机的类。您不应使用此类依赖项,因为 Oracle JVM 的内部 API 可能会在未来版本中更改,并且此名称空间可能不会由其他非 Oracle JVM 实现提供。(实际上,即使是Android 的 JVM也 附带使用更广泛的sun.*类之一。)

然后是Sun Microsystems用于实现其 Java 应用程序的com.sun.*命名空间。合法使用依赖的一个例子是 Sun 的 Jersey 框架,它最初部署在命名空间中。(为了完整起见,请注意最近的 Jersey 版本部署在从 2.0 版开始的命名空间中,这与 Jersey 1 API 不兼容。)为了进一步参考,请注意 Oracle在讨论问题时甚至没有提及命名空间通过使用命名空间强加。另外,请参阅Stack Overflow 上的相关问题。com.sun.*com.sun.jersey.*org.glassfish.jersey.*com.sun.*sun.*

因此,与依赖com.sun.*项相比,使用依赖项是不同的交易sun.*。通过使用com.sun.*类,您宁愿将自己锁定到特定库的 API,而不是特定 JVM。例如,您可以com.sun.jersey.*通过使用标准化的JAX-RS javax.ws.rs.*名称空间来避免直接使用名称空间。从这个意义上说,com.sun.*依赖关系是产品特定的和专有的,不能与通常在命名空间中找到的 Java 标准化 API 混淆javax.*

如果我是你,我会坚持使用成熟且公认的实现。Oracle 非常坚决不破坏 API(否则,他们可能还会将 taglet 移动到com.oracle.*. 如果他们愿意,您只需要更新您的技术。如果您的应用程序因新的 Java 版本而中断,您的用户会来寻找您的软件的更新。因为您不运行 taglet 项目,所以我同意您的观点,即从外部 API 中分离您的逻辑通常是一个好主意,因为它适用于任何依赖项。此外,在您的用例中使用 taglets 非常符合KISSDRY原则。

于 2014-04-24T06:55:11.337 回答