标签: documentation

我有一个没有Javadoc的大型代码库,我想运行一个程序来编写一个带有基本Javadoc信息的骨架(例如,对于每个方法的参数写@param ...),所以我只需要填补剩下的空白.

任何人都知道一个很好的解决方案？

编辑:

JAutodoc是我一直在寻找的.它有Ant任务,一个Eclipse插件,并使用Velocity进行模板定义.

您使用哪些工具/网站来阅读JavaDocs？

我目前使用的Firefox在打开J2EE项目时打开了20多个标签,以获得所有可用的文档,这些文档不是很有用,占用的内存太多而且无法搜索.

我对这样一个工具/网站的期望是:

• 聚合来自不同位置的JavaDoc
• 直接访问Eclipse中的Ctrl + T等类型
• 全文搜索
• 我选择的所有Java库之间的交叉引用
• 对于工具:离线支持
• 速度

不是强制性的:

• 注释事物的可能性
• 支持不同版本的库(+ diffing？)
• IDE集成

编辑:

谢谢你的回答.我知道大多数网站,但又给了他们一次尝试.这是我的判断:

• 内置的Eclipse/IDE功能
  • 紧密结合
  • 离线/在线支持
• javadoconline.com(不再维护)
  • 作品
  • 干净的样子
  • 在多个版本的api中查找匹配项,并允许轻松切换
  • 简单但有效
  • 快速
• jdocs(离线)
  • 看起来非常复杂
  • 有时慢
  • 似乎缺少一些最新版本的库(Seam 2.0.0,Hibernate Validators),但看起来你可以自己添加它们
  • IDE集成(未测试)
  • 每个项目的维基风格评论
• docjar.com
  • 作品
  • 快速
  • 杂乱的用户界面
• javadoc_isearch
  • firefox的greasemonkey脚本,使导航javadoc更容易
  • 工作顺利,完美

我正在记录我在C#中编写的一些处理解析令牌的方法.由于系统其他领域的一些技术限制,这些令牌需要采用XML元素的形式(即<tokenName />).我想将这些令牌的格式放在摘要语句中.

但是,这会引发错误:格式错误 - 名称以无效字符开头".是否有任何类型的转义字符序列可用于在我的C#摘要注释中嵌入XML？

我想要一些工具,最好是一个插入VS 2008/2010的工具,它将通过我的方法并添加关于它们可能抛出的异常的XML注释.我不希望<summary>为我生成或其他XML标记,因为我将自己填写,但如果即使在private/ protected方法我可以看到可以抛出哪些异常也会很好.否则,我发现自己经历了这些方法并将其悬停在其中的所有方法调用中以查看异常列表,然后更新该方法的<exception列表以包含这些.也许一个VS宏可以做到这一点？

由此:

private static string getConfigFilePath()
{
    return Path.Combine(Environment.CurrentDirectory, CONFIG_FILE);
}

对此:

/// <exception cref="System.ArgumentException"/>
/// <exception cref="System.ArgumentNullException"/>
/// <exception cref="System.IO.IOException"/>
/// <exception cref="System.IO.DirectoryNotFoundException"/>
/// <exception cref="System.Security.SecurityException"/>
private static string getConfigFilePath()
{
    return Path.Combine(Environment.CurrentDirectory, CONFIG_FILE);
}

更新: 看起来工具必须递归地遍历这些方法,例如,method1调用method2,它调用method3,记录为throw NullReferenceException,因此method2和method1都被工具记录为throw NullReferenceException.该工具还需要消除重复,如果方法中的两个调用被记录为抛出DirectoryNotFoundException,该方法将只列出<exception cref="System.IO.DirectoryNotFoundException"/>一次.

或者他们和它只是不在源头？我真的很想得到一些东西,它会阻止js-doc-toolkit在每次分析jQuery时吓坏我.这也意味着我无法使用jQuery作为依赖项正确记录任何代码,而不至少放置一些样板js-doc块,这些块无法正确记录jQuery的结构.我不知道有一个共同的解决方案吗？我试过谷歌搜索,顺便说一句.

使用ReST/Sphinx标记RESTful Web服务的方法/ URL的最佳方法是什么？是否存在适合使用可能的参数,HTTP方法,标题和正文内容标记URL的默认域？

有点像:

.. rest:method:: GET /api/foo

   :param bar: A valid bar
   :extension: json or xml

   Retrieve foos for the given parameters. E.g.::

      GET /api/foo.json?bar=baz

这样的事情是否已经存在或者是可用的默认扩展之一,还是我必须自己编写一个？

最近,我想使用该OpenCV库Python,但Python绑定的文档OpenCV非常不清楚和不足.我想问一下在哪里可以找到一些详细的Python绑定文档OpenCV.以前我用OpenCV的C++,和文档是非常有帮助,更在我可以去它的源代码,在那里我是个疑问.但是Python我认为,绑定的源代码并没有提供太多信息.例如,我需要很长时间才能发现CV_8UC1标志位于模块中cv2.CV_8UC1,但标志CV_CAP_PROP_FPS位于模块中cv2.cv.CV_CAP_PROP_FPS.

为其他语言生成API文档有很多很好的选择,但我还没有找到我想在GitHub页面上托管的JavaScript API的解决方案.似乎我可以使用JSDoc3,但我需要创建一个输出Jekyll标记的自定义插件.

我还想将代码URL链接到GitHub本身.我发现jsdoc-githubify会使输出更改链接,但我更喜欢一个更直接的选项,我有更多的控制权.

我是否必须创建自己的JSDoc插件,或者是否有一个我错过的更好的解决方案.人们用这个做什么？

真正让我反感Boost的是他们的文档.我需要的是一个很好的参考,而不是解释什么是一个很好的参考,我会举例:

java.sun.com/javase/6/docs/api/是的,我喜欢它.它也是:cppreference.com/wiki/stl/vector/start

另一方面,我发现有关boost的内容是这样的:http: //www.boost.org/doc/libs/1_40_0/libs/smart_ptr/shared_ptr.htm

基本上是一些长文本.几乎没有格式化,一些大胆的文本在这里和那里,希望元素之间的一些链接.更不用说smart_ptr是更好的文档库之一.

如果您没有找到此示例与上述示例之间的区别,请停止阅读并忽略此帖子.不要误会我的意思,我写C++并使用Boost.在我的公司,我们至少使用了4个库,但是每次我需要检查一个方法原型时,例如它让我从脑子里滚动浏览他们的文章.是的,我知道Boost是一个协作项目,不同的团队由不同的团队开发.

那么你们中的任何人都对Boost的参考感到失望吗？你知道一些更好的网站记录Boost库吗？

有时我想在stdlib中查找函数的实现,我已经下载了源代码,但它非常混乱.

因为许多命中,因为greping并不适合.

有没有人知道具有文档的网页doxygen风格.

Linux内核也是如此.

谢谢