Различия

Здесь показаны различия между двумя версиями данной страницы.

--- nodejs:jsdoc [2022/05/13 10:39]
werwolf
+++ nodejs:jsdoc [2023/01/12 12:18] (текущий)
@@ Строка 1: / Строка 1: @@
+===== Стандартизация комментариев JavaScript (JSDoc) =====
+===== Предисловие =====
+Как говорится, нет правила без правил; хотя код набирается и передается компилятору для интерпретации и выполнения, до тех пор, пока нет грамматических ошибок и ошибок форматирования, независимо от того, насколько античеловечен набор, нет проблем, но код - это еще одно широкое применение, помимо выполнения Просто прочтите его, просмотрите свой прошлый код, разберитесь в исходном коде других людей и т. Д., Так что существует стилизация кода, которая может улучшить внешний вид, но при этом его легко читать.
+Конечно, помимо самого кода, дополнительное чтение может быть связано с комментариями к коду. Сами комментарии не будут компилироваться и выполняться компилятором, и их роль заключается в том, чтобы оставить некоторую информацию, чтобы облегчить лучшее понимание самого кода; поэтому прокомментированные Стандартизация - это тоже вопрос, над которым стоит подумать; и следующий вопрос будет представлен**JSDoc** Это такой инструмент;
+===== JSDoc =====
+Согласно его официальному сайту ([[https://jsdoc.app/index.html|https://jsdoc.app/index.html]]) Введение, JSDoc - это генератор документов API для JavaScript, похожий на Javadoc в Java или phpDocumentor в PHP; добавьте комментарии в указанном формате в исходный код, и инструмент JSDoc автоматически просканирует ваш код и сгенерирует API Веб-сайт документа (сгенерировать связанные файлы веб-страницы в указанном каталоге);
+Создание документации по API - это только один аспект. Его основной вклад заключается в стандартизации формата комментариев кода. Возможно, вы не использовали его, но большинство из вас где-то видели в исходном коде формат комментариев, подобный следующему:
+<code javascript>
+/**
+ * Returns the sum of a and b
+ * @param {number} a
+ * @param {number} b
+ * @returns {number}
+ */
+function sum(a, b) {
+    return a + b;
+}
+</code>
+==== использовать ====
+Пользоваться инструментом очень просто, сначала установите его:
+<code powershell>
+npm install -g jsdoc
+</code>
+Во-вторых, предположим, что в ''doc.js'' Напишите в файл следующий код:
+<code javascript>
+/**
+ * Returns the sum of a and b
+ * @param {number} a
+ * @param {number} b
+ * @returns {number}
+ */
+function sum(a, b) {
+    return a + b;
+}
+/**
+ * Return the diff fo a and b
+ * @param {number} a
+ * @param {number} b
+ * @returns {number}
+ */
+function diff(a, b) {
+    return a - b;
+}
+</code>
+Затем выполните следующую команду в текущем каталоге:
+<code javascript>
+jsdoc doc.js
+</code>
+Наконец, файл с именем ''out'' Содержимое текущего каталога станет следующим:
+<code javascript>
+├── doc.js
+└── out
+    ├── index.html
+    ├── doc.js.html
+    ├── global.html
+    ├── fonts
+    │   ├── OpenSans-BoldItalic-webfont.eot
+    │   ├── OpenSans-BoldItalic-webfont.svg
+    │   ├── OpenSans-BoldItalic-webfont.woff
+    │   ├── OpenSans-Bold-webfont.eot
+    │   ├── OpenSans-Bold-webfont.svg
+    │   ├── OpenSans-Bold-webfont.woff
+    │   ├── OpenSans-Italic-webfont.eot
+    │   ├── OpenSans-Italic-webfont.svg
+    │   ├── OpenSans-Italic-webfont.woff
+    │   ├── OpenSans-LightItalic-webfont.eot
+    │   ├── OpenSans-LightItalic-webfont.svg
+    │   ├── OpenSans-LightItalic-webfont.woff
+    │   ├── OpenSans-Light-webfont.eot
+    │   ├── OpenSans-Light-webfont.svg
+    │   ├── OpenSans-Light-webfont.woff
+    │   ├── OpenSans-Regular-webfont.eot
+    │   ├── OpenSans-Regular-webfont.svg
+    │   └── OpenSans-Regular-webfont.woff
+    ├── scripts
+    │   ├── linenumber.js
+    │   └── prettify
+    │       ├── Apache-License-2.0.txt
+    │       ├── lang-css.js
+    │       └── prettify.js
+    └── styles
+        ├── jsdoc-default.css
+        ├── prettify-jsdoc.css
+        └── prettify-tomorrow.css
+</code>
+Посетите это через браузер ''out'' Связанные веб-страницы в каталоге будут отображать контент, подобный следующим страницам;
+Домашняя страница:
+{{:nodejs:7a790d6680b04ece105b4d5c9c17efb5.png|}}
+Укажите страницу функции:
+{{:nodejs:17f2a89fe89a9f5ff6fcb0c5a4d43b88.png|}}
+\\ Шаблон стиля веб-страницы также можно заменить, просто измените его в соответствии с параметрами командной строки, я не буду рассматривать его здесь, давайте узнаем о формате его комментариев;
+==== Формат комментария ====
+Пожалуйста, обратитесь к официальному веб-сайту для полного ознакомления с форматом ([[https://jsdoc.app/index.html|https://jsdoc.app/index.html]]), текущая версия - JSDoc 3. Ниже представлены только несколько часто используемых тегов и приведены примеры; конечно, если сложно написать кучу тегов, многие редакторы (например, VS Code) теперь предоставляют соответствующие загрузки подключаемых модулей непосредственно в подключаемом модуле. Будет много поисковых ключевых слов jsdoc, которые генерируются с подсказками или автоматически распознают текущий код, что очень удобно;
+=== Комментарий ===
+JSDoc использует следующий формат символов комментария для обертывания тегов, которые будут добавлены на уровне блока:
+<code javascript>
+/**
+ *
+ *
+ */
+</code>
+То есть столбец звездочки выровнен по вертикали. Используйте две звездочки в первой строке и добавьте пробел после каждой звездочки перед записью содержимого, например:
+<code javascript>
+/**
+   * Оставьте пробел перед описанием
+   * Или многострочное описание
+   * @param {number} описание параметра
+ */
+</code>
+Встроенный пакет:
+<code javascript>
+/** @function */
+</code>
+=== @description ===
+Также можно написать''@desc'', Чтобы описать подробную информацию о текущем объекте аннотации;
+<code javascript>
+/**
+ * @function
+   * @description о введении функции
+ */
+function myFn() {}
+/**
+   * Вы также можете написать введение прямо здесь
+ * @function
+   * @description. Если вы продолжите использовать теги для добавления содержимого сюда, оно перезапишет вводное содержимое в первой строке.
+ */
+function myFn() {}
+</code>
+=== @file ===
+Комментарий записывается в начале файла, чтобы описать соответствующую информацию о текущем файле; например:
+<code javascript>
+/**
+   * @file Это файл для ..., содержит ... функции
+ */
+// Тогда тело кода ...
+</code>
+=== @author ===
+Опишите соответствующую информацию об авторе текущего файла или кода;
+<code javascript>
+/**
+ * @author Jack <jack@example.com>
+ */
+</code>
+=== @copyright ===
+Опишите информацию об авторских правах текущего файла
+<code javascript>
+/**
+ * @copyright Jack 2020
+ */
+</code>
+=== @license ===
+Опишите информацию, относящуюся к текущей лицензии на файл;
+<code javascript>
+/**
+ * @license MIT
+ */
+</code>
+или:
+<code javascript>
+/**
+ * @license
+ * Copyright (c) 2015 Example Corporation Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ * ...
+ */
+</code>
+=== @version ===
+Опишите номер версии текущего проекта;
+<code javascript>
+/**
+   * Эта версия исправляет ... проблемы
+ * @version 1.2.3
+ */
+</code>
+=== @since ===
+Опишите, в какой версии была введена функция;
+<code javascript>
+/**
+ * Обеспечить ... функцию
+ * @since 1.2.1
+ */
+function newFn() {}
+</code>
+=== @see ===
+Подобно значениям «см. Также» и «см. Подробно», вы также можете использовать его для навигации в другие места.''@link'' Перейти к определенному сетевому адресу;
+<code javascript>
+/**
+ * @see fn2
+ */
+function fn1() {}
+/**
+ * @see {@link http://example.com|some text}
+ */
+function fn2() {}
+</code>
+=== @todo ===
+Опишите, что делать дальше;
+<code javascript>
+/**
+   * @todo add ... функция
+   * @todo fix ... ошибка
+ */
+function myFn() {}
+</code>
+=== @function ===
+против ''@func'', ''@method'' То же самое означает описание функции;
+<code javascript>
+/** @function */
+var myFn = function() {}
+</code>
+=== @type ===
+Опишите тип переменной;
+<code javascript>
+/**
+   * Переменная типа объекта
+ * @type {object}
+ */
+var val1 = {};
+/**
+   * Переменная символьного или числового типа
+ * @type {(string|number)}
+ */
+var val2;
+/**
+   * Тип - числовой или пустой
+ * @type {?number}
+ */
+var val3;
+/**
+   * Тип числовой или не может быть пустым
+ * @type {!number}
+ */
+var val4;
+/**
+   * Массив экземпляров класса MyClass
+ * @type {Array.<MyClass>}
+ */
+var arr = new MyClass();
+/**
+   * Массив строк
+ * @type {string[]}
+ */
+var arr2 = ['a', 'b', 'c'];
+/**
+   * Объект, содержащий строку и числовой тип
+ * @type {object.<string, number>}
+ */
+var obj1 = {a: 'one', b: 2}
+/**
+   * Укажите конкретные ключи и типы объектов
+ * @type {{a: string, b: number}}
+ */
+var obj2 = {a: 'one', b: 2}
+/**
+   * Укажите конкретные ключи и типы именованных объектов
+ * @type {object} obj3
+ * @type {string} obj3.a
+ * @type {number} obj3.b
+ */
+var obj3 = {a: 'one', b: 2}
+</code>
+=== @param ===
+против ''@arg'', ''@argument'' То же самое означает описание информации о параметрах функции;
+<code javascript>
+/**
+   * За меткой следует тип параметра, затем имя параметра и, наконец, описание параметра.
+   * @param {number} a Напишите здесь описание переменной
+   * @param {string} b- или добавьте дефис для удобства чтения
+   * @param {string} c-Или этот параметр имеет очень длинный, очень длинный
+   * Очень длинное, очень длинное, очень длинное, очень длинное, очень длинное описание, которое может занимать несколько строк
+ */
+function myFn(a, b, c) {}
+/**
+   * Переданный параметр является объектом
+   * @param {object} option - параметр объекта, переданный в
+   * @param {строка} option.name - свойство имени объекта
+   * @param {number} option.age - свойство возраста объекта
+ */
+function myFn(option) {
+    var name = option.name;
+    var age = option.age;
+}
+/**
+   * Переданный параметр представляет собой массив строк
+   * @param {string []} arr - параметр входящего объекта
+ */
+function myFn(arr) {
+    var name = option.name;
+    var age = option.age;
+}
+/**
+   * Указывает, что параметр необязательный
+   * @param {number} a-это обязательный параметр
+   * @param {number} [b] - это необязательный параметр.
+   * @param {number =} c-другое представление необязательных параметров
+ */
+function myFn(a, b, c) {}
+/**
+   * Указывает значение по умолчанию необязательного параметра
+ * @param {number} a
+   * @param {number} [b = 3] - значение по умолчанию 3
+ */
+function myFn(a, b) {}
+/**
+   * Различные представления типов параметров
+   * @param {number} a-type - это число
+   * @param {number | string} b-тип - число или строка
+   * @param {? number} c-тип - число или null (null)
+   * @param {! number} d-тип - это число, а не пусто
+   * @param {*} e-Нет ограничений по типу, это может быть любой тип
+ */
+function myFn(a, b, c, d, e) {}
+/**
+   * Означает функцию с любым количеством параметров
+   * Следующая функция возвращает сумму всех входящих параметров
+   * @param {... number} num - любое количество параметров, но все они имеют числовой тип
+ */
+function sum(num) {
+    var len = arguments.length;
+    var result = 0;
+    for (let i = 0; i < len; i++) {
+        result += arguments[i];
+    }
+    return result;
+}
+</code>
+=== @typedef ===
+Используется для описания типов пользовательских переменных;
+<code javascript>
+/**
+   * Описание нестандартного типа
+ * @typedef {(string|number)} myType
+ */
+/**
+   * Описание нестандартного типа
+   * @type {myType} val - использовать произвольный тип
+ */
+function myFn(val) {}
+</code>
+=== @callback ===
+Опишите информацию о параметрах указанной функции как функцию обратного вызова;
+<code javascript>
+/**
+   * Это описание функции обратного вызова
+ * @callback myCallback
+   * @param {string} aa - параметры, принимаемые функцией обратного вызова
+   * @param {number} [bb] - еще один необязательный параметр, принимаемый функцией обратного вызова
+ */
+/**
+   * Это описание самой функции
+ * @param {string} a
+   * @param {myCallback} функция обратного вызова-обратного вызова
+ */
+function myFn(a, callback) {}
+</code>
+=== @returns ===
+Или напишите ''@return'', Информация, описывающая возвращаемое значение функции;
+<code javascript>
+/**
+ * @param {number} a
+   * @returns {number} описание возвращаемого значения
+ */
+function myFn(a) {
+    return a + 1;
+}
+/**
+ * @param {number} a
+   * @returns {(number | string)} Возвращаемое значение может быть числом или символьным типом.
+ */
+function myFn2(a) {
+    if (a > 1) {
+        return 1;
+    } else {
+        return 'no.';
+    }
+}
+</code>
+=== @example ===
+Опишите пример использования указанного кода;
+<code javascript>
+/**
+   * Добавьте образец кода (формат будет выделен)
+ * @param {string} a
+ * @param {string} b
+ * @returns {string} return a concat b.
+ *
+ * @example
+ * console.log(myFn('hello ', 'world!'));
+ * // "hello world!"
+ */
+function myFn(a, b) {
+    return a + b;
+}
+</code>
+=== @class ===
+Опишите ''class'' учебный класс;
+<code javascript>
+/**
+   * Описание категории
+ * @class
+ */
+class MyClass {}
+/**
+   * Или конструктор
+ * @class
+ */
+function MyClass() {}
+var ins = new MyClass();
+</code>
+=== @namespace ===
+Опишите пространство имен;
+<code javascript>
+/**
+   * Укажите объект в пространстве имен
+ * @namespace
+ */
+var MyNamespace = {
+    /**
+           * Представлен как MyNamespace.fn
+     * @returns {*}
+     */
+    fn: function() {},
+    /**
+           * Представлен как MyNamespace.a
+     * @type {number}
+     */
+    a: 1
+}
+/**
+   * Вручную укажите пространство имен
+ * @namespace MyNamespace
+ */
+/**
+   * Функция-член MyNamespace.myFn
+ * @function
+ * @returns {*}
+ * @memberof MyNamespace
+ */
+function myFn() {}
+</code>
+=== @member ===
+Описать член текущего класса;
+<code javascript>
+/**
+ * @class
+ */
+function MyClass() {
+    /** @member {string} */
+    this.name = 'knightyun';
+    /**
+           * Или виртуальный участник
+     * @member {number} age
+     */
+}
+</code>
+=== @memberof ===
+Опишите класс, к которому принадлежит член;
+<code javascript>
+/**
+ * @class
+ */
+class MyClass {
+    /**
+     * @constructor
+     * @memberof MyClass
+     */
+    constructor() {}
+    /*
+     * @param {string} val
+     * @returns {*}
+     * @memberof MyClass
+     */
+    myFn(val) {}
+}
+</code>

Инструменты пользователя

Инструменты сайта

Различия

Инструменты страницы