我正在编写一个库,它将已经单元测试的示例代码(它的源代码、输出和任何输入文件)插入到 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.sun
taglets。com.sun
但是,我尽可能地“瘦”这种依赖。也就是说,我将尽可能少的代码放在 taglet 类中,将大部分代码留在不依赖com.sun
. - 我致力于创建自己的解析器,它只搜索我的特定 taglets。这是一种痛苦,但并不可怕。您遍历每个 Java 源文件的行,搜索
\{@\.myTagletName (.*?)\}
. 捕获该文本后,它与com.sun
taglet 中的代码几乎相同。 - 这个解析器必须在执行 javadoc 之前运行,因此需要一个重复的目录结构。(1) 您的原始代码,带有未解析的自定义标签,(2) 该代码的副本,带有解析的输出。我将所有代码复制到重复目录,然后仅解析那些已知具有这些标记的 Java 文件(以某种方式使用解析器“注册”的类)。
这是一个合理的方法吗?是否已经有更多的跨平台 javadoc/taglet 解析器,所以我不必自己动手?有没有什么跨平台的东西已经存在了?JavaDoc本身不是跨平台的,还是只是自定义的 taglet 和 doclet?
由于这个决定(使用内联标签),我想大致了解有多少人被锁定在我的图书馆之外,但主要是我正在寻找一个长期的解决方案。
(尽管上面有我的 Java 8 链接,但我使用的是 Java 7。)
感谢 @fge 提出的 taglet 建议,这比我最初的想法更优雅,感谢 @Michael 提供不祥但有用的com.sun
警告。