标签: documentation-generation

我有一个小代码库,我正在用YARD记录.当我运行yardoc命令时,它告诉我:

Files:          40
Modules:        14 (    0 undocumented)
Classes:        39 (    0 undocumented)
Constants:      21 (    4 undocumented)
Methods:       239 (   31 undocumented)
 88.82% documented

我希望它只是列出未记录的项目,而不是浏览我的所有代码来查找未记录的常量和方法.有人知道怎么做吗？

对于ActionScript 2,我使用过NaturalDocs.但是它对PHP的支持很差.到目前为止我看过doxygen和phpDocumentor,但是我认为它们的输出非常难看.有没有人有PHP自动文档生成的经验？我更喜欢能够使用javadoc风格的标签,它们很容易编写并且易于记忆.

当我以PDF格式生成Doxygen文档时,我会获得大量不同的文件,每个文件都有一个图表.
是否有可能获得单个PDF文档,组织为书籍,大致与HTML版本一样？
是否可以自动获取,即​​无需手动处理乳胶文件？

谢谢!

我需要为我的javascript项目选择一个文档生成器(类似于java中的jdoc或ruby中的rdoc)(使用jquery,下划线和主干构建)

候选人:

• jsdoc工具包
• PDOC
• 自然文档
• docco
• YUI doc
• doctool http://jquery.bassistance.de/docTool/docTool.html
• 其他？

要求

• 应该使用jquery,下划线和主干.这意味着对象 - 文字方法等
• 我真的很喜欢pdoc,但它过于集中在原型,文档记录很差,而且我不想制作额外的文件(部分？)以使其工作(不确定)
• docco很好,但我想要结构化输出(如菜单+类/ func结构,如jdoc)
• 必须是命令行/ makefile兼容(不是web pastie)

提示,技巧,教程,成功案例,建议大受欢迎.

为什么jQuery不使用JSDoc？

在Sphinx中,如果我有以下标题声明:

.. _somestuff:

``this is code``, this is not!
==============================

它渲染,像这样:

    this is code, 这不是!

哪个好,但是,如果我使用参考,例如:

Have a look at :ref:`somestuff`

它丢失了代码格式并呈现如下:

    看看这是代码,这不是!

代替:

    看看this is code,这不是!

是否可以在引用中保留代码格式？我该怎么办呢？

我有一些关于Swift文档注释的问题.

1. 反正有没有像一些Apple文档那样制作一个相关的声明部分.例如,当我选择+单击tablewView(_:heightForRowAtIndexPath :)方法时,它会将我链接到生成的文档中的其他3个相关方法.

2. swift中有警告标签吗？我知道在objective-c中它允许你做@warning并在生成的文档中得到一个粗体警告.但是,:警告:在快速文档评论中没有任何作用,所以我很好奇是否还有其他方法.

3. 有没有办法让您的文档成为与Apple文档类似格式的HTML文件.我知道在其他IDE中用于其他语言,例如Eclipse,您只需为代码生成html文档.XCode有这个吗？

我试过以下,

/*
 * addRelationship
 *
 * Adds a relationship between two entities using the given relation type.
 *
 * @param fromKey the original entity
 * @param toKey the referring entity
 * @param relationTypeDesc the type of relationship
 */

function addRelationship($fromKey, $toKey, $relationTypeDesc) {
    $relationTypeKey = $this->getRelationTypeKey($relationTypeDesc);

但是,当我试图在另一个地方使用它时,它说PHPDoc没有找到.

关于如何在NetBeans PHP中使用它的任何想法？

更新:

以下是可在NetBeans PHP中使用的更新语法 -

/** 
 * addRelationship
 *
 * Adds a relationship between two entities using the given relation type.
 *
 * @param integer $fromKey the original entity
 * @param integet …

我需要为我创建的REST API编写一些api文档.是否有工具可以在下划线api文档中找出类似风格的html输出？或者也许某些东西会输出一些作为Twitter引导风格的html？

我看到docco确实编写了代码,但我实际上只是想要记录API.理想情况下,我想在控制器文件中指出一个工具,让它生成有关方法和路由的文档,但不显示任何源代码,除非我特别说出示例.

我正在尝试找到一个为我的Javascript源代码生成HTML文档的工具.

有谁知道Google用于在以下网址生成界面的工具是否是开源的？我能够产生类似的输出吗？

http://closure-library.googlecode.com/svn/docs/class_goog_proto2_Serializer.html

http://closure-library.googlecode.com/svn/docs/namespace_goog_date.html

http://closure-library.googlecode.com/svn/docs/namespace_goog_events.html

http://closure-library.googlecode.com/svn/docs/class_goog_gears_Database.html

http://closure-library.googlecode.com/svn/docs/class_goog_ui_DatePicker.html

我知道http://code.google.com/p/jsdoc-toolkit/

但是我想知道Google使用的特定生成器是否可用于我自己的源(如果这很重要的话,它将是开源的).

提前致谢...

编写类和方法的代码内文档通常在哪里？

您是否在标题(.hpp)文件或源(.cpp)文件中的相应类/方法之上编写了这样的doc-blocks？

对这类事情有一个广受尊重的公约吗？大多数C++项目是以一种方式而不是另一种方式来做的吗？

或者文档应该写在双方(即.hpp和.cpp文件中),可能只有一个简短的描述,一个是另一个更长的一个？

最重要的是,是否有任何实际的考虑因素使得以一种方式而不是另一种方式编写它更方便？(例如使用Doxygen等自动文档解析器和生成器......)