如何使需要com.sun的内联标签更加跨平台？是否有非Oracle/更跨平台的javadoc解析器？

Question

如何使需要com.sun的内联标签更加跨平台？是否有非Oracle/更跨平台的javadoc解析器？

7

我正在编写一个库，它可以将已经单元测试过的示例代码（其源代码、输出和任何输入文件）插入到JavaDoc中，并具有许多自定义选项。使用该库的主要方式是使用内联标签，例如。

{@.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()}

由于自定义标签（甚至文档标签）需要com.sun，这意味着它们不像Java本身那样跨平台。（不确定是否相关，但单词“javadoc”——甚至子字符串“doc”——不在Java 8语言规范中。）

我不喜欢编写受此限制的库的想法。那么我该怎么办？我目前的想法是

为了利用现有的javadoc解析器，我使用com.sun标签。但是，我尽可能地将对com.sun的依赖性减少到最低限度。也就是说，我在标签类中尽可能少地放置代码，将大部分代码留在其他地方，在那里不依赖于com.sun。

我致力于创建自己的解析器，仅搜索我的特定标签。这很麻烦，但不太可怕。您可以迭代每个Java源文件的行，搜索\{@\.myTagletName (.*?)\}。一旦捕获该文本，它与com.sun标签中的代码基本相同。

此解析器必须在执行javadoc之前运行，因此需要一个重复的目录结构。（1）原始代码，带有未解析的自定义标记，（2）该代码的副本，带有解析输出。我会将所有代码复制到重复目录中，然后仅解析已知具有这些标签的Java文件（以某种方式“注册”在解析器中的类）。

这是一个合理的方法吗？是否已经有更跨平台的javadoc/taglet解析器，以便我不必自己编写？是否已经有类似taglet的跨平台工具存在？JavaDoc本身是否不跨平台，还是只有自定义的taglets和doclets不跨平台？

我想大致了解由于使用内联taglets而无法使用我的库的人数，但主要是寻找长期解决方案。

（尽管上面我提供的是Java 8链接，但我正在使用Java 7。）

感谢 @fge 提供的标签建议，比我最初的想法更加优雅，也感谢 @Michael 提供的不祥但有帮助的 com.sun 警告。

- aliteralmind

如果您感兴趣，我现在已经完成了这个库。它叫做 Codelet：http://codelet.aliteralmind.com 和 https://github.com/aliteralmind/codelet。 - aliteralmind

1个回答

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- Rafael Winterhalter · Accepted Answer

首先，需要注意 sun.* 和 com.sun.* 依赖项之间的区别。 sun.* 命名空间包含实现 Oracle 的 Java 虚拟机的类。您不应该使用这些依赖项，因为 Oracle JVM 的内部 API 可能会在未来的版本中更改，并且此命名空间可能不会由其他非 Oracle JVM 实现提供。（事实上，即使 Android 的 JVM 附带了其中一个最常用的 sun.* 类。）

然后还有com.sun.*命名空间，Sun Microsystems用它来实现其Java应用程序。使用com.sun.*依赖项的合法示例是Sun的Jersey框架，最初部署在com.sun.jersey.*命名空间中。（为了完整起见，请注意最近的Jersey版本{{link3：部署}}在org.glassfish.jersey.*命名空间中，从2.0版本开始，这与Jersey 1 API不兼容。）此外，请注意Oracle在讨论使用sun.*命名空间所带来的问题时甚至没有提到com.sun.*命名空间。另请参见Stack Overflow上的{{link5：相关问题}}。

因此，使用com.sun.*依赖库与sun.*依赖库是不同的。使用com.sun.*类将使您锁定到特定库的API，而不是特定的JVM。例如，您可以通过使用标准化的JAX-RSjavax.ws.rs.*命名空间来避免直接使用com.sun.jersey.*命名空间。在这个意义上，com.sun.*依赖库是产品特定和专有的，不应与通常在javax.*命名空间中找到的Java标准化API混淆。

如果我是你，我会坚持使用taglets，这是一种成熟且被认可的实现。Oracle非常决心不打破API（否则，他们可能也会将taglets移动到com.oracle.*），我看不出他们突然改变taglet包结构的理由。如果他们这样做了，你只需要更新你的技术。如果你的应用程序因为新的Java版本而崩溃，你的用户会寻找你的软件更新。因为你不运行taglet项目，所以我同意你从外部API中分离逻辑通常是个好主意，就像任何依赖关系一样。此外，对于你的用例使用taglets基本上承认了KISS和DRY原则。