===== Стандартизация комментариев 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>