我正在编写一个库,该库将已经经过单元测试的示例代码(其源代码,输出和任何输入文件)插入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” 。)
我不喜欢编写这样限制的库的想法。那我该怎么办?到目前为止,我的想法是
com.sun
标记。但是,我com.sun
尽可能地依靠“瘦”。也就是说,我将尽可能少的代码放在taglet类中,而将大部分代码留在了不依赖的其他地方com.sun
。\{@\.myTagletName (.*?)\}
。捕获该文本后,它与com.sun
标签中的代码几乎相同。这是合理的方法吗?已经有一个跨平台的javadoc / taglet解析器了,所以我不必自己动手?有什么跨平台,taglet- 像已经在那里?JavaDoc 本身不是跨平台的,还是仅仅是自定义标签和doclet?
由于这个决定(使用内联标签),我想对我被锁定在图书馆之外的人数有一个大概的了解,但是我主要是在寻找长期解决方案。
(尽管上面有我的Java 8链接,但我使用的是Java7。)
感谢@fge提供的标签建议(比我最初的想法更优雅)以及@Michael提供的不祥但有用的com.sun
警告。
首先,请注意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分离逻辑通常是一个好主意,因为对于任何依赖项都是如此。另外,在您的用例中使用标记几乎可以识别KISS和DRY原则。
本文收集自互联网,转载请注明来源。
如有侵权,请联系 [email protected] 删除。
我来说两句