如何使用 jsdoc-toolkit 记录匿名函数（闭包）

Posted 2023-02-21

【中文标题】如何使用 jsdoc-toolkit 记录匿名函数（闭包）

【英文标题】：How to document anonymous functions (closure) with jsdoc-toolkit

【发布时间】：2011-12-25 16:38:03

【问题描述】：

我正在尝试使用 JSDoc-toolkit 记录我的代码。我的代码首先被一个自动执行的匿名函数包装。我到底如何记录这一点？我几乎整天都在这上面。 JS Docs 将无法识别匿名函数闭包内的任何内容，因为它不知道如何处理它。它坏了，我的cmets都没有通过。

我的代码看起来像这样。

/** 
 * @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);
 ());

谢谢！

【问题讨论】：

那是因为 JSDoc 完全是 java 主义，不适合 javascript。只需编写明智的 cmets 即可

谢谢你，rjmunro。我同意。我根本不认为它过于本地化。但是，从那以后，我已经切换到 Docco 来获取文档。 jashkenas.github.com/docco/

【参考方案1】：

您不能直接记录嵌套函数。但你可以这样做：

/**
 * @module foobar
 */

/**
* @function
* @author Baa
* @name hello 
* @description Output a greeting
* @param String name - The name of the person to say hello
*/
(function hello(name) 
    /**
     * @function
     * @author Baz
     * @inner
     * @private
     * @memberof module:foobar
     * @description Check if the argument is a string (see: @link module:foobar~hello)
     * @param String string - The string
     * @returns String Returns true if string is valid, false otherwise
     */ 
    var isString = function checkString(string)  return typeof string === 'string'; ;
    if (isString(name))
      console.log('Hello ' + name + '!');
('Mr. Bubbles'));

这里我将checkString 设置为 private 和 inner 是描述性的（因为无法描述嵌套函数），然后我传入@987654324 @ 记录私有函数。最后，我添加一个指向父函数的链接以供参考。

我认为jsdoc 是不必要的挑剔，需要用更好的东西代替。它是javadoc 的一个端口，所以它有很多与Java 相关但与JS 无关的东西，反之亦然。有一些非常常见的 JS 习惯用法，例如 closures 或 nested functions，很难或不可能记录。

我总是检查我的名称路径并使用--explain 标志进行调试。

【讨论】：

你也可以看看***.com/questions/50330518/…

【参考方案2】：

您可以像这样将@namespace 与@name 和@lends 一起使用：

/**
* @name MyNamespace
* @namespace Hold all functionality
*/
(function () 
    "use strict";
    /** @lends MyNamespace*/
    var stlib = function (param, param, param)  ...All of my code...;
());

【讨论】：

我很抱歉。这并没有真正回答我想要做的事情。我用更多信息更新了代码 sn-p。不过还是谢谢你的回复！

javascript 中没有命名空间。这个结构甚至没有意义

@Raynos 他们不是语言有什么区别？他们是injsdoc。也许语义上不是真的，但我写的，它有效。

@Microfed 我觉得它不可读然后我又发现 jsdoc 是一个肮脏的 Java 仿真，其中包含太多不适用的构造

@Raynos 是的，有许多结构不适用。许多在内部做完全相同的事情（例如@ aguments 和@extends）。使用您认为有用的东西并丢弃其他所有东西是您的工作。