标签: code-documentation

我知道这不是最重要的问题,但我只是意识到我可以在注释之前或之后放置javadoc注释块.我们希望采用什么作为编码标准？

/**
 * This is a javadoc comment before the annotation 
 */
@Component
public class MyClass {

    @Autowired
    /**
     * This is a javadoc comment after the annotation
     */
    private MyOtherClass other;
}

如何告诉JSDoc有关返回的对象的结构.我找到了@return {{field1: type, field2: type, ...}} description语法并试了一下:

/**
 * Returns a coordinate from a given mouse or touch event
 * @param  {TouchEvent|MouseEvent|jQuery.Event} e    
 *         A valid mouse or touch event or a jQuery event wrapping such an
 *         event. 
 * @param  {string} [type="page"]
 *         A string representing the type of location that should be
 *         returned. Can be either "page", "client" or "screen".
 * @return {{x: Number, y: Number}} 
 *         The location of the event
 */
var getEventLocation …

我有一个接受一个字符串参数的函数.此参数只能包含一些已定义的可能值.记录相同内容的最佳方法是什么？应该将shapeType定义为enum或TypeDef还是其他什么？

Shape.prototype.create = function (shapeType) {
    // shapeType can be "rect", "circle" or "ellipse"...
    this.type = shapeType;
};

Shape.prototype.getType = function (shapeType) {
    // shapeType can be "rect", "circle" or "ellipse"...
    return this.type;
};

问题的第二部分shapeType是在文件中不知道可能的值,它定义shapeType为您建议的任何内容.有几个开发人员提供了多个文件,可能会添加可能的值shapeType.

PS:我正在使用 jsdoc3

对于项目中的每个类,SandCastle创建(以及其他)两个页面:

• 主页面,称为T_class_full_name,带有描述,语法,继承层次结构和另请参阅
• 成员页面,称为AllMembers_T_class_full_name,带有构造函数,方法,字段等.

有没有办法将这两者合并在一起 - members page附加到主页面？

我目前正在使用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,还看了很多其他看起来相当过时的文章...)

我正在编写一些我刚编写的新代码,并将NDoc sytle注释添加到我的类和方法中.我希望生成一个非常好的MSDN样式文档供参考.

一般来说,在为类和方法编写注释时,有哪些好的指导原则？NDoc评论应该说什么？他们应该怎么说？

我发现自己正在研究.NET框架评论所说的内容,但这种情况会变得很快; 如果我能有一些好的规则来指导自己,我可以更快地完成我的文档.

如何在Xcode中为我自己的代码创建快速帮助条目？我只是想把它作为编码支持,就像编写Java时的Eclipse功能一样.在eclipse中,当您将方法悬停在其他位置时,您会在方法上方输入注释.

Xcode等效似乎是"快速帮助".

除了使用Doxygen之外真的没别的办法吗？对于我正在研究的小项目来说,Doxygen似乎有些过分.目前我确实知道我只想彻底填写快速帮助,所以请避免任何提示,"你必须为你的项目创建一个文档".

我真的很感激任何帮助,因为我在这个主题上唯一能找到的就是这个问题.

但正如您所看到的,没有可用的解决方案.

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

所以这可能是一个愚蠢的问题,但我现在已经搜索了很长一段时间,即使我经常在源代码中看到它们,我也无法弄清楚它们的作用.

我刚刚将我的项目迁移到swift 3中,发现"看到"的快速帮助标注没有显示出来.在以前版本的swift中,一切都完美无缺.以下是我的代码

/**
 Adds a See also callout to the Quick Help for a symbol using the See Also delimiter. Multiple See also callouts appear in the description section in the same order as they do in the markup..

 - author: Tapas Pal

 - remark: Use the callout to add references to other information.

 - seealso: [The Swift Standard Library Reference](https://developer.apple.com/library/prerelease/ios//documentation/General/Reference/SwiftStandardLibraryReference/index.html)

 */
class SeeAlsoMarkup: NSObject {
    static func doSomething() {}
}

输出就像

Apple是否通过此标记更改了任何内容？但是它的文档仍然显示相同.