JSDoc 注释中的 JSDoc 注释答案

【问题标题】：JSDoc comment within a JSDoc commentJSDoc 注释中的 JSDoc 注释
【发布时间】：2015-06-02 17:42:21
【问题描述】：

我给出的 JSDoc cmets 代码示例也包含 JSDoc cmets，如何在不破坏外部注释的情况下转义嵌套的 JSDoc 注释？

我正在使用版本 3.3.0-beta3

例子：

 /**
  * @example
  * /**
  *  * Description.
  *  * @alias ...
  *  * @extends ...
  *  * @constructor
  *  */
  * function Something() {
  *     ...
  * }
  * ...
  */
 function MyFun() {
 ...

嵌套的*/ 当然会破坏评论。额外的空间将阻止* / 或*\/，然后 - 当然 - 出现在我不想要的 JSDoc 文档中。

有什么办法可以避免这种情况，使生成的 JSDoc 看起来像正确的代码？

【问题讨论】：

标签： javascript comments jsdoc

【解决方案1】：

我不知道有什么方法可以避免这种情况，但你可以编写一个简单的插件来解决

exports.handlers = {
    newDoclet : function(doclet) {
        if(doclet.example){
            doclet.example = doclet.example.replace(/*\//g,'*/');
        }
    }
};

请注意，我还没有尝试过，但它应该可以解决问题。

【讨论】：

【解决方案2】：

如果您愿意在 Markdown 代码块而不是 JSDoc @example 块中使用示例，您可以启用 Markdown 插件，如 here 所述，并使用 HTML character references 转义一个或多个有问题的嵌套注释字符，如下所示：

/**
 * Example:
 *
 *     &#47;**
 *      * Description.
 *      * @alias ...
 *      * @extends ...
 *      * @constructor
 *      *&#47;
 *     function Something() {
 *         ...
 *     }
 *     ...
 */
function MyFun() {
...

已经过测试，可以与 JSDoc 3.3.2 一起使用。

【讨论】：