＋设为首页 ＋添加到收藏夹
对于大多数 java 类库来说,javadoc 是唯一的文档.而且,除了商业软件组件之外,许多 java 类不会用到 javadoc.虽然 javadoc 作为 api 参考工具很出色,但对于了解类库是如何组织的与应该如何使用它来说,它却是一种十分差劲的方法.并且即便用了 javadoc,它通常只包含有关方法完成了什么的最基本信息,而忽略了诸如错误处理.参数及返回值的作用域与范围.线程安全.锁定行为.前置条件.后置条件.不变条件或副作用之类的重要特性.
【程序编程相关:从魔兽中的英雄设计机制来窥探面向对象的思】向 javadoc 学习 【推荐阅读:一个操作注册表的类】
大多数 java 包都有某种“根”对象,它是在得到该工具内的任何其它对象之前,必须创建的第一个对象.在 jndi 中,该根对象是 context,而在 jms 与 jdbc 中,它是 connection.如果有人告诉您 jdbc 中的基础对象是 connection,以及如何获得这一对象,那么接着您很可能会从 javadoc 中通过仔细察看 javadoc 中可用的方法列表找到如何创建并执行 statement,以及如何迭代生成的 resultset.但您如何知道获得 connection 是您的第一步呢?javadoc 在包内按照字母顺序组织类,在类中按照字母顺序组织方法.遗憾的是,javadoc 中没有神奇的“从这里开始（start here）”记号把读者带到浏览 api 的逻辑开始位置. 【扩展信息:使用PB调用API自动更新（非FTP模式】
对于包括大多数开放源码包与大多数内部开发的组件在内的许多 java 工具而言,实际情况是:包括 javadoc 在内,几乎所有类库或组件都不具有有效的文档.这就意味着开发人员要从 javadoc 学习使用工具,而且我们应该考虑根据这一现实组织我们的 javadoc.我经常开玩笑说:现在,java 程序员需要具备的最重要的技能之一是熟练地使用 google 与 javadoc 来对那些文档编制得十分糟糕的 api 进行“逆向工程”.这可能是真的,但却并不十分好笑.包描述
最接近“从这里开始”记号的是包描述,但它却很少得到有效的使用.如果将文件 package.html 与源代码一起放在一个包中,那么标准的 doclet 会将已生成的 package-summary.html 文件中的内容连同类列表一起放在该包内.... 下一页