让我们面对现实:您不需要成为设计师就能看到默认的Javadoc看起来很难看.
网上有一些资源可以提供重新设计的Javadoc.但默认行为代表产品,应该看起来相当好看.
另一个问题是,与其他类似资源相比,Javadoc的可用性并不是最新的.
特别是巨大的项目很难使用Firefox的快速搜索进行导航.
实际问题:
是否有任何独立(桌面)应用程序能够以比浏览器更有用的方式浏览现有的Javadoc？
我正在考虑像Mono的文档浏览器这样的东西.
理论问题:
有没有人知道,如果有一些计划以某种方式标准化的方式发展Javadoc？
编辑: 有关此主题的Sun维基的有用链接.
我创建了一个Markdown(java)Doclet,它将在Markdown格式的文本中获取源注释并创建相同的HTML Javadoc.
新的doclet还对文本进行了一些重新设置,但生成的HTML在此阶段不会更改.
这在一定程度上解决了HTML-in-java-commenting问题,这可能是当前Javadoc最大的可用性问题.
我不认为Javadoc的概念已经过时了.据我所知,这些概念多年前在一个名为doxygen的产品中扎根,该产品仍可用于其他语言(即大量使用的Objective-C).即使这有它的前辈 - 看看Donald Knuth使用的编程环境来创建TeX(Literate编程).
然而,拥有程序代码和文档的单一来源是一个有趣的想法.
除此之外,还可以使用JavaDoc工具支持的插件系统根据您的特殊需求定制文档.您可以提供一个插件(我们这样做)直接发布到可以通过Web直接访问的数据库中.使用协作,任何人都可以对文档提供其他注释或说明,这些注释或说明可能会回到原始源代码中.
Javadoc是我见过的最好的源代码自动文档生成系统.很大一部分就是它如此简单 - 如果我愿意的话,我甚至可以用我5岁的手机浏览javadoc!虽然我同意有点整容可能是有序的,特别是JDK是一个很难浏览,我不敢完全重新发明轮子,因为我们现在拥有的是一个RESTful,易于使用的解决方案,其目的是有效的几乎任何地方.
我最近收到一封邮件,称Sun正在努力使Javadoc HTML输出现代化.从邮件说:
我们建议对JDK7的javadoc/doclet进行改进.项目维基页面位于 http://wikis.sun.com/display/Javadoc/Home.作为提议改进的一部分,将重新调整javadoc输出的UI.新的设计截图被上传到项目维基.javadoc输出标记将被修改为有效的HTML和WCAG 2.0兼容.
所以那里肯定还有工作,即使有点迟了.然而,在我看来,Javadoc最大的缺点之一就是它与HTML的紧密结合.许多类都有Javadoc,它包含文字HTML,并且依赖于输出也是HTML.不幸的是,我认为这不会随时改变.尽管如此,这意味着开发人员可以自由地在HTML中包含任何他们想要的内容,这些内容可能也是无效的,非格式良好等等.因此,调整javadoc工具的输出只是其中的一部分,另一部分赢了t并且不能改变因此仍然存在.
至于浏览文档,我也发现HTML文档有点笨拙.我通常在Eclipse中使用Javadoc视图.它也有缺点(速度慢,你不能真正搜索),但它对大多数事情来说都是Good Enough™.
为了回答你的实际问题,我用Google搜索并问朋友并提出了这些问题.Forrestdoc,doclet和doxygen.
第二个问题,我会说是的,它不是非常"Web-oh-twoeye",但至少你保证在离线环境中工作,并且它足够小,可以与你的API一起发布.我决定使用框架,但它对javadoc工作得相当好.我没有看到任何改变它的计划.就阅读,解释和生成它而言,Eclipse对javadoc有一些支持.
就个人而言,我仍然觉得Javadoc非常有用.特别是因为它是标准化的.我不知道任何主要的文档样式,我觉得更容易导航(这可能很主观,但我个人觉得MSDN使用起来很糟糕).
对于搜索:使用Javadoc搜索框架,它使得使用各种Javadoc变得更加容易.它可以作为Firefox的用户脚本和Google Chrome扩展程序使用.
京公网安备 11010802040832号 | 京ICP备19059560号-6 