JSDoc注释中的JSDoc注释

Question

我会给出带有JSDoc注释的代码示例，其中还包含JSDoc注释，如何在不破坏外部注释的情况下转义嵌套的JSDoc注释？

我正在使用版本3.3.0-beta3

示例：

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

嵌套的*/会打断注释。加一个额外的空格可以避免这种情况，使用* /或*\/, 这样-当然-会在JSDoc文档中显示出来，但我不想要这样。

有没有办法转义这个字符，使生成的JSDoc看起来像正确的代码？

- Sam

Answer 1

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

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

请注意，我没有尝试过这个方法，但它应该能解决问题。

- SGD

Answer 2

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

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

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

- dharcourt