标签: documentation

编辑:这在技术上是一个2部分问题.我选择了一般性问题的最佳答案,并与处理特定问题的答案相关联.

使用jsdoc记录匿名对象和函数的最佳方法是什么？

/**
 * @class {Page} Page Class specification
 */
var Page = function() {

    /**
     * Get a page from the server
     * @param {PageRequest} pageRequest Info on the page you want to request
     * @param {function} callback Function executed when page is retrieved
     */
    this.getPage = function(pageRequest, callback) {
    }; 
};

无论是PageRequest对象还是callback存在于代码中.它们将getPage()在运行时提供.但我希望能够定义对象和功能是什么.

我可以创建PageRequest用于记录的对象:

/**
 * @namespace {PageRequest} Object specification
 * @property {String} pageId ID of the page you want.
 * …

Mogenerator的帮助很小.所有参数做什么？

Linux中是否存在C++文档？我想要类似C的手册页.例如,字符串,stl,iostream,ifstream等的文档？

我不久前开始使用Sandcastle为我们的一个项目生成一个文档网站.它工作得很好,但我们始终只在项目中编写类,方法,属性(...)的文档,并为整个项目和项目部件/模块/命名空间提供完全独立的文档.如果我可以将这些文档合并在一起并将相应的文档添加到生成的帮助文件中,那将是很好的,但我无法弄清楚如何做到这一点.

只是在命名空间声明中添加注释似乎不起作用(C#):

/// <summary>
/// My short namespace description
/// </summary>
namespace MyNamespace { ... }

有谁知道如何做到这一点？我知道有可能以某种方式,这将是非常好的... :)

我使用Java Jersey(和JAXB)编写了一个非常广泛的REST API.我还使用Wiki编写了文档,但它是一个完全手动的过程,非常容易出错,特别是当我们需要进行修改时,人们往往忘记更新wiki.

从四处查看,大多数其他REST API也可以手动创建文档.但我想知道这是否可能是一个很好的解决方案.

需要为每个端点记录的事物类型是:

• 服务名称
• 类别
• URI
• 参数
• 参数类型
• 响应类型
• 响应类型架构(XSD)
• 样本请求和响应
• 请求类型(获取/放置/发布/删除)
• 描述
• 可能返回的错误代码

然后当然有一些全球性的事情,如

• 安全
• REST概述
• 错误处理
• 等等

这些一般的东西可以描述一次并且不需要自动化,但对于Web服务方法本身来说,似乎非常希望自动化它.

我想过可能会使用注释,编写一个生成XML的小程序,然后是一个XSLT,它应该用HTML生成实际的文档.使用自定义XDoclet更有意义吗？

我正在尝试从我的模块中创建一个文档.我pydoc在Windows 7中使用Python 3.2.3从命令行使用:

python "<path_to_pydoc_>\pydoc.py" -w myModule

这导致我的shell充满了文本,我的模块中的每个文件都有一行,说:

no Python documentation found for '<file_name>'

这就像Pydoc试图获取我的文件的文档,但我想自动创建它.我找不到使用谷歌的好教程.有没有人有关于如何使用Pydoc的任何提示？

如果我尝试使用一个文件创建文档

python ... -w myModule\myFile.py

此外,它在我的计算机上有一个指向文件本身的链接,我可以单击它,它会在我的网络浏览器上显示文件内部的内容.

我目前正在使用JSDoc Toolkit来记录我的代码,但它不太适合 - 也就是说,它似乎很难正确地描述命名空间.假设每个文件中有两个简单的类:

lib/database/foo.js:

/** @class */
function Foo(...) {...}

/** @function ... */
Foo.prototype.init(..., cb) { return cb(null, ...); };

module.exports = foo;

然后继承了一些东西lib/database/bar.js:

var Foo = require('./foo');

/**
 * @class
 * @augments Foo
 */
function Bar(....) {...}

util.inherits(Bar, Foo);

Bar.prototype.moreInit(..., cb) { return cb(null, ...); };

在生成的文档中,这个输出只是Foo和Bar,没有前导database(或lib.database),当你没有全局范围内的所有东西时,这是非常必要的.

我试着扔@namespace database,并@name database.Foo在它,但它并没有变成好的.

任何使JSDoc输出更合适的想法,或者一些完全不同的工具,使用Node.js更好？(我简要地看了一下自然文档,JSDuck,还看了很多其他看起来相当过时的文章...)

我想知道link当我尝试使用新包编写文档时,存在一种从其他包中运行的方法roxygen2.有点像\link{pck=PACKAGE_NAME, fun=FUNCTION_NAME}？

(注意:我意识到这很接近你如何记录你的数据库结构？但我不认为它是相同的.)

我已经开始在一个拥有数百个表和视图的数据库的地方工作,所有这些都使用含有非常少的元音的神秘名称,而且没有文档.他们也不允许对数据库模式进行无偿更改,也不能触摸除我自己的机器上的测试数据库之外的任何数据库(它会被吹走并定期重新创建),因此我无法添加可以帮助任何人的注释.

我尝试使用"Toad"来创建一个ER图,但是在让它连续运行48小时之后它仍然没有产生任何可见的东西,我需要我的电脑.我正在和其他一些最近招聘的人员谈话,我们都建议每当我们弄清楚某个特定表格或其中某些列的含义时,我们应该在开发人员维基中更新它.

那么有什么好办法呢？只需列出表格/视图及其列,并在我们去的时候填写它们？我必须掌握的基本工具是Toad,Oracle的"SQL Developer",MS Office和Visio.

这一直困扰着我一段时间.当我看到任何以文本打印的Ruby方法时,它通常显示为:

Class#method

要么

#method

现在,我会用:

Class.method

为什么所有Ruby方法都以井号开头？有什么理由吗？只是好奇.