如何使内嵌标签(需要com.sun)更加跨平台?是否有非Oracle /跨平台Javadoc解析器?

敏锐的

我正在编写一个库该库已经经过单元测试的示例代码(其源代码,输出和任何输入文件)插入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()}

由于自定义标记(甚至doclets)需要使用com.sun,因此这意味着它们与Java本身的跨平台不一样。(不确定这是否相关,但是Java 8语言规范中没有单词“ javadoc”,甚至子字符串“ doc” 。)

我不喜欢编写这样限制的库的想法。那我该怎么办?到目前为止,我的想法是

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

这是合理的方法吗?已经有一个跨平台的javadoc / taglet解析器了,所以我不必自己动手?有什么跨平台,taglet- 已经在那里?JavaDoc 本身不是跨平台的,还是仅仅是自定义标签和doclet?

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

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


感谢@fge提供的标签建议(比我最初的想法更优雅)以及@Michael提供的不祥但有用的com.sun警告。

拉斐尔·温特豪德(Rafael Winterhalter):

首先,请注意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甚至没有提到命名空间通过使用名称空间来强加另外,请参阅有关堆栈溢出的相关问题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.*依赖关系是特定于产品的并且是专有的,不得与通常在javax.*名称空间中找到的Java标准化API混淆

如果我是你,我会坚持使用标签,这是一种成熟且公认的实现。Oracle坚决不破坏API(否则,它们可能还会将taglet移至com.oracle.*),我看不出它们会突然更改taglet包结构的原因。如果愿意,您只需要更新您的技术即可。如果您的应用程序因新的Java版本而中断,则您的用户将寻找软件的更新。因为您没有运行taglet项目,所以我同意您的观点,即从任何外部API分离逻辑通常是一个好主意,因为对于任何依赖项都是如此。另外,在您的用例中使用标记几乎可以识别KISSDRY原则。

本文收集自互联网,转载请注明来源。

如有侵权,请联系 [email protected] 删除。

编辑于
0

我来说两句

0 条评论
登录 后参与评论

相关文章