如何使内联taglet（需要com.sun）更跨平台？是否有非Oracle /更跨平台的javadoc解析器？ [英] How to make inline taglets (which require com.sun) more cross-platform? Is there a non-Oracle/more-cross-platform javadoc parser?

问题描述

我正在编写库，其中插入了已经过单元测试过的示例代码（它的源代码，输出和任何输入文件）到JavaDoc中，具有许多自定义功能。使用此库的主要方式是使用内联标记，例如

I'm writing a library that inserts already unit-tested example code (its source-code, output, and any input files) into JavaDoc, with lots of customization possibilities. The main way of using this library is with inline taglets, such as

{@.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语言规范。）

Since custom taglets (and even doclets) require com.sun, this means they're not nearly as cross platform as Java itself. (Not sure if this is relevant, but the word "javadoc"--and even the substring "doc"--is not in the Java 8 Language Specifications.)

我不喜欢编写库的想法这种方式有限。那我该怎么办？到目前为止我的想法是

I don't like the idea of writing a library that's limited in this way. So what do I do? My thoughts so far are that

• 为了利用现有的javadoc解析器，我坚持使用 com .sun taglets。但是，我依赖 com.sun 作为瘦。也就是说，我尽可能少地在taglet类中编写代码，将大部分代码留在别处，而不依赖于 com.sun 。


• 我致力于创建自己的解析器，仅搜索我的特定标记。这是一种痛苦，但并不太可怕。您遍历每个Java源文件的行，搜索 \ {@ \.myTagletName（。*？）\} 。捕获该文本后，它与 com.sun 标记中的代码几乎相同。


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

• In order to take advantage of the existing javadoc parser, I stick with the com.sun taglets. However, I make this reliance on com.sun as "thin" as can be. That is, I put as little code in the taglet class as possible, leaving the bulk of the code elsewhere, where there is no reliance on com.sun.
• I work towards creating my own parser, which only searches for my specific taglets. This is a pain, but not too horrible. You iterate through the lines of each Java source file, searching for \{@\.myTagletName (.*?)\}. Once you capture that text, it's pretty much the same as the code within the com.sun taglet.
• This parser would have to be run before executing javadoc, and would therefore require a duplicate directory structure. (1) your original code, with the unparsed custom tags, (2) the duplicate of that code, with parsed-output. I'd copy all code to the duplicate directory, and then parse only those Java files known to have these taglets (classes that are "registered" in some way with the parser).

这是一种合理的方法吗？是否有更多的跨平台javadoc / taglet解析器，所以我不必自己动手？是否有任何跨平台的taglet- 就像那样？ JavaDoc 本身是不是跨平台，还是只是自定义标记和doclet？

Is this a reasonable approach? Is there a more cross-platform javadoc/taglet parser out there already, so I don't have to roll my own? Is there anything cross-platform that is taglet-like already out there? Is JavaDoc itself not cross platform, or just custom taglets and doclets?

我想对我有多少人有一个粗略的看法因为这个决定而锁定我的库（使用内联taglet），但主要是我正在寻找一个长期的解决方案。

I'd like a rough perspective on how many people I'm locking out of my library because of this decision (to use inline taglets), but mostly I'm looking for a long term solution.

（尽管我上面的Java 8链接，我正在使用Java 7.。

(Despite my Java 8 link above, I'm using Java 7.)

@fge对于taglet建议的信用，这比我的优雅更优雅最初的想法，以及@Michael的不祥但有用的 com.sun 警告。

Credit to @fge for the taglet suggestion, which is more elegant than my original idea, and to @Michael for the ominous-but-helpful com.sun warnings.

推荐答案

首先，请注意 sun之间存在差异。 * 和 com.sun。* 依赖项。 sun。* 命名空间包含实现Oracle Java虚拟机的类。您不应使用此类依赖项，因为Oracle JVM的内部API可以在将来的版本中进行更改，因为其他非Oracle JVM实现可能不提供此命名空间。 （实际上，甚至 Android的JVM 附带一个更广泛使用的 sun。* classes。）

At first, note that there is a difference between sun.* and com.sun.* dependencies. The sun.* namespace contains classes that implement Oracle's Java Virtual Machine. You should not use such dependencies because the Oracle JVM's internal API can change in future releases and because this namespace may not be provided by other, non-Oracle JVM implementations. (In practice, even Android's JVM ships with one of the more widely used sun.* classes.)

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

Then there is the com.sun.* namespace which was used by Sun Microsystems for implementing its Java applications. An example for legal use of com.sun.* dependencies is Sun's Jersey framework which was originally deployed in the com.sun.jersey.* namespace. (For the sake of completeness, note that recent Jersey versions are deployed in the org.glassfish.jersey.* namespace beginning with version 2.0 which is incompatible to the Jersey 1 API.) For further reference, note how Oracle does not even mention the com.sun.* namespace when discussing the problems that are imposed by using the sun.* namespace. Also, see this related question on Stack Overflow.

因此，与 sun相比，使用 com.sun。* 依赖项是一个不同的交易。* 依赖项。通过使用 com.sun。* 类，您宁愿将自己锁定到特定库的API，而不是特定的JVM。例如，您可以通过使用标准化的 com.sun.jersey。* 命名空间wiki / Java_API_for_RESTful_Web_Servicesrel =nofollow noreferrer> JAX-RS javax.ws.rs。* 名称空间。从这个意义上讲， com.sun。* 依赖项是特定于产品和专有的，不得与Java的标准化API混淆，后者通常位于 javax中。* 名称空间。

Therefore, using com.sun.* dependencies is a different deal compared to sun.* dependencies. By using com.sun.* classes, you rather lock yourself to a specific library's API, not to a specific JVM. For example, you can avoid direct use of the com.sun.jersey.* namespace by using the standardized JAX-RS javax.ws.rs.* namespace. In this sense, com.sun.* dependencies are product specific and proprietary and must not be confused with Java's standardized APIs which are usually found in the javax.* namespace.

如果我是你，我会坚持使用这是一个成熟且公认的实施方案。 Oracle非常坚定不要破坏API （否则，他们会可能还会将taglet移动到 com.oracle。* ），我认为他们没有理由突然改变taglet包结构。如果他们愿意，你只需要更新你的技术。如果您的应用程序因新Java版本而中断，您的用户将会寻找您的软件更新。因为你没有运行taglet项目，所以我同意你的看法，从外部API中分离你的逻辑通常是一个好主意，因为它适用于任何依赖项。此外，为您的用例使用taglet几乎可以识别 KISS 和 DRY 原则。

If I was you, I would stick with the taglets which is a mature and recognized implementation. Oracle is pretty determined not to break APIs (otherwise, they would probably also move the taglets to com.oracle.*) and I see no reason why they would suddenly change the taglet package structure. And if they would, you merely need to update your tech. If your application breaks for a new Java release, your users will come looking for an update of your software. Because you do not run the taglet project, I agree with you that detaching your logic from a foreign API is in general a good idea as it is for any dependency. Also, using taglets for your use case pretty much recognizes the KISS and DRY principles.

这篇关于如何使内联taglet（需要com.sun）更跨平台？是否有非Oracle /更跨平台的javadoc解析器？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！