标签: jsdoc

我有下面的 JavaScript 代码，并且我正在使用 TypeScript 编译器 (TSC) 根据Typescript Docs JSDoc Reference提供类型检查。

const assert = require('assert');
const mocha = require('mocha');

mocha.describe('Array', () => {
    mocha.describe('#indexOf()', () => {
        mocha.it('should return -1 when the value is not present', 
        /** */
        () => {
            assert.strictEqual([1, 2, 3].indexOf(4), -1);
        });
    });
});

我看到这个错误：

Assertions require every name in the call target to be declared with an explicit type annotation.ts(2775)
SomeFile.test.js(2, 7): 'assert' needs an explicit type annotation.

我该如何解决这个错误？

我需要为我的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？

所有官方JSDoc示例都有简单的文档字符串,如下所示:

/**
 * @param {string} author - The author of the book.
 */

问题是,在现实文档中,您通常需要更长的文档字符串:

/**
 * @param {string} author - The author of the book, presumably some person who writes well
 */

但由于大多数公司(出于合法的可读性原因)都有线路长度限制,因此上述情况往往是不可接受的.然而,我无法弄清楚的是分解这些线的"正确"方式应该是什么.

我可以:

/**
 * @param {string} author - The author of the book, presumably some
 * person who writes well
 */

但这很难理解.我可以这样做:

/**
 * @param {string} author - The author of the book, presumably some
 *                          person who writes well
 */

这看起来更好,但它可能导致大量的行,特别是如果参数具有长名称:

/**
 * @param {string} personWhoIsTheAuthorOfTheBook - …

该@param标签允许性质的文件,如

 /**
  * @param {Object} userInfo Information about the user.
  * @param {String} userInfo.name The name of the user.
  * @param {String} userInfo.email The email of the user.
  */

我如何记录@this标签的属性？

 /**
  * @this {Object} 
  * @param {String} this.name The name of the user.
  * @param {String} this.email The email of the user.
  */

我想知道是否有人在该项目上工作.(文档仍在创建......)

我想指出一个参数应该是一个DOM节点,但我似乎无法找到有关如何用JSDoc指示的信息.我可以使用{Object},但这很难看.我宁愿有类似{Node}或{DOMNode},但我找不到任何的例子指向我这个方向努力.

那么,如何将参数标记为期望DOM节点？

我正在尝试使用JSDoc-toolkit记录我的代码.我的代码首先包含一个自执行的匿名函数.我怎么在世界上记录这个？我几乎整天都在这上面.JS Docs不会识别匿名函数闭包内部的任何内容,因为它不知道如何处理它.它打破了,我的评论都没有通过.

我的代码看起来像这样.

/** 
 * @fileoverview BLA BLA BLA
 */

/**
 * This is where I don't know what to put.
 */
 (function () {
     "use strict";

     /** or here */
     var stlib = function (param, param, param) {
         /** or here */
         var share = {
             /** or here */
             config: {
                 button: DOM Element,
                 property: blablabla
             },

             init: function () { ...some init code here}
         };

         share.init();
     };

     widgets.add("share", stlib);
 }());

谢谢!

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

目前在我的项目中我们使用JSDoc,我们最近开始实现Angular,我想继续使用JSDoc来确保所有文档都在同一个地方.

我看过人们主要只是说使用ngDoc,但这不是一个可行的选择,因为我们总是会有单独的JavaScript,理想情况下我会将所有内容放在一起.

/**
 * @author Example <jon.doe@example.com>
 * @copyright 2014 Example Ltd. All rights reserved.
 */
(function () {
    window.example = window.example || {};
    /**
     * Example Namespace
     * @memberOf example
     * @namespace example.angular
     */
    window.example.angular = window.example.angular || {};
    var exAngular = window.example.angular;

    /**
     * A Example Angular Bootstrap Module
     * @module exampleAngularBootstrap
     */
    exAngular.bootstrap = angular.module('exampleAngularBootstrap', [
            'ngRoute',
            'ngResource',
            'ngCookies'
        ])
        .run(function ($http, $cookies) {
            $http.defaults.headers.post['X-CSRFToken'] = $cookies.csrftoken;
            $http.defaults.headers.common['X-CSRFToken'] = $cookies.csrftoken;
        });
})();

目前这是我所拥有的但是无法为run()提供任何想法的文档？

简单的问题,我如何记录"混合型"？我知道我可以列出所有可能的类型,{null|undefined|String|Number|Object}并最终发现自己错过了一个并使其过于复杂.我尝试使用Mixed关键字,但它会在许多IDE中弹出错误,例如WebStorm.

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

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

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