Добавление пользовательского содержимого в сгенерированные документы JSDoc

Question

Мы работаем над переписыванием нашей документации по API и хотели бы добавить пользовательский контент в созданные нами документы JSDoc. Этот пользовательский контент может, например, быть запускаемыми фрагментами кода, что является функцией, которую мы в настоящее время имеем в наших документах, написанных вручную (на основе внедрения динамического контента Jekyll). Есть ли способ добиться этого напрямую, используя систему шаблонов JSDoc и некоторый пользовательский код сегодня, или косвенно , путем постобработки сгенерированного html в поисках каких-то символов? Другие генераторы JSDoc, которые могут справиться с этим, также представляют интерес.

Скажем, у нас могло бы быть что-то вроде этого

      /**
 * @param {String} foo
 * @runnableExample foo-example
 */

будет генерировать какой-то пользовательский код для этого @runnableExampleкод, который будет вставлять файл с именем ./examples/foo-example.js. Это просто предложение для хорошего пользовательского опыта, но не так, как должно быть.

Answer 1

JSDoc CLI имеет полезный флаг, который вы можете использовать для проверки (и обработки) метаданных из ваших аннотаций:

      /**
 * @return {number}
 */
function answer() {
  return 42;
}

      $ jsdoc -X tmp/example.js

      [
    {
        "comment": "/**\n * @return {number}\n */",
        "meta": {
            "range": [
                28,
                62
            ],
            "filename": "example.js",
            "lineno": 4,
            "columnno": 0,
            "path": "/workspace/dev/tmp",
            "code": {
                "id": "astnode100000002",
                "name": "answer",
                "type": "FunctionDeclaration",
                "paramnames": []
            }
        },
        "returns": [
            {
                "type": {
                    "names": [
                        "number"
                    ]
                }
            }
        ],
        "name": "answer",
        "longname": "answer",
        "kind": "function",
        "scope": "global",
        "params": []
    },
    {
        "kind": "package",
        "longname": "package:undefined",
        "files": [
            "/workspace/dev/tmp/example.js"
        ]
    }
]

Но как насчет пользовательских тегов? -Xflag будет обрабатывать и их:

      /**
 * @answer 42
 */
function answer() {
  return 42;
}

      [
    {
        "comment": "/**\n * @answer 42\n */",
        "meta": {
            "range": [
                22,
                56
            ],
            "filename": "example.js",
            "lineno": 4,
            "columnno": 0,
            "path": "/workspace/dev/tmp",
            "code": {
                "id": "astnode100000002",
                "name": "answer",
                "type": "FunctionDeclaration",
                "paramnames": []
            }
        },
        "tags": [
            {
                "originalTitle": "answer",
                "title": "answer",
                "text": "42",
                "value": "42"
            }
        ],
        "name": "answer",
        "longname": "answer",
        "kind": "function",
        "scope": "global",
        "params": []
    },
    {
        "kind": "package",
        "longname": "package:undefined",
        "files": [
            "/workspace/dev/tmp/example.js"
        ]
    }
]

Как видите, вывод представляет собой чистый JSON, что упрощает его обработку с помощью JavaScript или любых приличных систем шаблонов. Я давно отказался от шаблонов JSDoc. я использую jsdoc -Xи сам обрабатываю аннотации.

Недавно я экспериментировал с JQ и EJS и отправил результат в Slate для создания веб-сайтов документации: https://customcommander.github.io/project-blueprint/#project-blueprint-fake-api — это веб-сайт документации для поддельный API.

То, чего вы хотите достичь, определенно выполнимо. Надеюсь, этого достаточно, чтобы вы начали. Если вы хотите узнать больше: https://github.com/customcommander/project-blueprint