nodejs:jsdoc []

Это старая версия документа!

Содержание

Стандартизация комментариев JavaScript (JSDoc)
Предисловие
JSDoc

Стандартизация комментариев JavaScript (JSDoc)

Предисловие

Как говорится, нет правила без правил; хотя код набирается и передается компилятору для интерпретации и выполнения, до тех пор, пока нет грамматических ошибок и ошибок форматирования, независимо от того, насколько античеловечен набор, нет проблем, но код - это еще одно широкое применение, помимо выполнения Просто прочтите его, просмотрите свой прошлый код, разберитесь в исходном коде других людей и т. Д., Так что существует стилизация кода, которая может улучшить внешний вид, но при этом его легко читать.

Конечно, помимо самого кода, дополнительное чтение может быть связано с комментариями к коду. Сами комментарии не будут компилироваться и выполняться компилятором, и их роль заключается в том, чтобы оставить некоторую информацию, чтобы облегчить лучшее понимание самого кода; поэтому прокомментированные Стандартизация - это тоже вопрос, над которым стоит подумать; и следующий вопрос будет представленJSDoc Это такой инструмент;

JSDoc

Согласно его официальному сайту (https://jsdoc.app/index.html) Введение, JSDoc - это генератор документов API для JavaScript, похожий на Javadoc в Java или phpDocumentor в PHP; добавьте комментарии в указанном формате в исходный код, и инструмент JSDoc автоматически просканирует ваш код и сгенерирует API Веб-сайт документа (сгенерировать связанные файлы веб-страницы в указанном каталоге);

Создание документации по API - это только один аспект. Его основной вклад заключается в стандартизации формата комментариев кода. Возможно, вы не использовали его, но большинство из вас где-то видели в исходном коде формат комментариев, подобный следующему:

/**
 * Returns the sum of a and b
 * @param {number} a
 * @param {number} b
 * @returns {number}
 */
function sum(a, b) {
    return a + b;
}

1
2
3
4
5
6
7
8
9

использовать

Пользоваться инструментом очень просто, сначала установите его:

npm install -g jsdoc

1

Во-вторых, предположим, что вdoc.js Напишите в файл следующий код:

/**
 * 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;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

Затем выполните следующую команду в текущем каталоге:

jsdoc doc.js

1

Наконец, файл с именемout Содержимое текущего каталога станет следующим:

├── 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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

Посетите это через браузерout Связанные веб-страницы в каталоге будут отображать контент, подобный следующим страницам;

Домашняя страница:

Укажите страницу функции:

Шаблон стиля веб-страницы также можно заменить, просто измените его в соответствии с параметрами командной строки, я не буду рассматривать его здесь, давайте узнаем о формате его комментариев;

Формат комментария

Пожалуйста, обратитесь к официальному веб-сайту для полного ознакомления с форматом (https://jsdoc.app/index.html), текущая версия - JSDoc 3. Ниже представлены только несколько часто используемых тегов и приведены примеры; конечно, если сложно написать кучу тегов, многие редакторы (например, VS Code) теперь предоставляют соответствующие загрузки подключаемых модулей непосредственно в подключаемом модуле. Будет много поисковых ключевых слов jsdoc, которые генерируются с подсказками или автоматически распознают текущий код, что очень удобно;

Комментарий

JSDoc использует следующий формат символов комментария для обертывания тегов, которые будут добавлены на уровне блока:

/**
 * 
 * 
 */

1
2
3
4

То есть столбец звездочки выровнен по вертикали. Используйте две звездочки в первой строке и добавьте пробел после каждой звездочки перед записью содержимого, например:

/**
   * Оставьте пробел перед описанием
   * Или многострочное описание
   * @param {number} описание параметра
 */

1
2
3
4
5

Встроенный пакет:

/** @function */

1

@description

Также можно написать@desc, Чтобы описать подробную информацию о текущем объекте аннотации;

/**
 * @function
   * @description о введении функции
 */
function myFn() {}

/**
   * Вы также можете написать введение прямо здесь
 * @function
   * @description. Если вы продолжите использовать теги для добавления содержимого сюда, оно перезапишет вводное содержимое в первой строке.
 */
function myFn() {}

1
2
3
4
5
6
7
8
9
10
11
12

@file

Комментарий записывается в начале файла, чтобы описать соответствующую информацию о текущем файле; например:

/**
   * @file Это файл для ..., содержит ... функции
 */
 
// Тогда тело кода ...

1
2
3
4
5

@author

Опишите соответствующую информацию об авторе текущего файла или кода;

/**
 * @author Jack <jack@example.com>
 */

1
2
3

@copyright

Опишите информацию об авторских правах текущего файла

/**
 * @copyright Jack 2020
 */

1
2
3

@license

Опишите информацию, относящуюся к текущей лицензии на файл;

/**
 * @license MIT
 */

1
2
3

или:

/**
 * @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:
 * ...
 */

1
2
3
4
5
6
7
8
9
10
11
12

@version

Опишите номер версии текущего проекта;

/**
   * Эта версия исправляет ... проблемы
 * @version 1.2.3
 */

1
2
3
4

@since

Опишите, в какой версии была введена функция;

/**
 * Обеспечить ... функцию
 * @since 1.2.1
 */
function newFn() {}

1
2
3
4
5

@see

Подобно значениям «см. Также» и «см. Подробно», вы также можете использовать его для навигации в другие места.@link Перейти к определенному сетевому адресу;

/**
 * @see fn2
 */
function fn1() {}

/**
 * @see {@link http://example.com|some text}
 */
function fn2() {}

1
2
3
4
5
6
7
8
9

@todo

Опишите, что делать дальше;

/**
   * @todo add ... функция
   * @todo fix ... ошибка
 */
function myFn() {}

1
2
3
4
5

@function

против @func, @method То же самое означает описание функции;

/** @function */
var myFn = function() {}

1
2

@type

Опишите тип переменной;

/**
   * Переменная типа объекта
 * @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}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

@param

против @arg, @argument То же самое означает описание информации о параметрах функции;

/**
   * За меткой следует тип параметра, затем имя параметра и, наконец, описание параметра.
   * @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;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68

@typedef

Используется для описания типов пользовательских переменных;

/**
   * Описание нестандартного типа
 * @typedef {(string|number)} myType
 */

/**
   * Описание нестандартного типа
   * @type {myType} val - использовать произвольный тип
 */
function myFn(val) {}

1
2
3
4
5
6
7
8
9
10

@callback

Опишите информацию о параметрах указанной функции как функцию обратного вызова;

/**
   * Это описание функции обратного вызова
 * @callback myCallback
   * @param {string} aa - параметры, принимаемые функцией обратного вызова
   * @param {number} [bb] - еще один необязательный параметр, принимаемый функцией обратного вызова
 */
 
/**
   * Это описание самой функции
 * @param {string} a
   * @param {myCallback} функция обратного вызова-обратного вызова
 */
function myFn(a, callback) {}

1
2
3
4
5
6
7
8
9
10
11
12
13

@returns

Или напишите@return, Информация, описывающая возвращаемое значение функции;

/**
 * @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.';
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

@example

Опишите пример использования указанного кода;

/**
   * Добавьте образец кода (формат будет выделен)
 * @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;
}

1
2
3
4
5
6
7
8
9
10
11
12
13

@class

Опишитеclass учебный класс;

/**
   * Описание категории
 * @class
 */
class MyClass {}

/**
   * Или конструктор
 * @class
 */
function MyClass() {}
var ins = new MyClass();

1
2
3
4
5
6
7
8
9
10
11
12

@namespace

Опишите пространство имен;

/**
   * Укажите объект в пространстве имен
 * @namespace
 */
var MyNamespace = {
    /**
           * Представлен как MyNamespace.fn
     * @returns {*}
     */
    fn: function() {},
    /**
           * Представлен как MyNamespace.a
     * @type {number}
     */
    a: 1
}

/**
   * Вручную укажите пространство имен
 * @namespace MyNamespace
 */
/**
   * Функция-член MyNamespace.myFn
 * @function
 * @returns {*}
 * @memberof MyNamespace
 */
function myFn() {}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

@member

Описать член текущего класса;

/**
 * @class
 */
function MyClass() {
    /** @member {string} */
    this.name = 'knightyun';
    
    /**
           * Или виртуальный участник
     * @member {number} age
     */
}

1
2
3
4
5
6
7
8
9
10
11
12

@memberof

Опишите класс, к которому принадлежит член;

/**
 * @class
 */
class MyClass {
    /**
     * @constructor
     * @memberof MyClass
     */
    constructor() {}
    /*
     * @param {string} val
     * @returns {*}
     * @memberof MyClass
     */
    myFn(val) {}
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

Техническая статья push

Мобильный телефон, совместное использование компьютерных программ

(function () { var size='728×90|300×250', adunit = 'russianblogs.com_728x90_responsive_5_DFP', childNetworkId = '22396446015', xmlhttp = new XMLHttpRequest();xmlhttp.onreadystatechange = function(){if(xmlhttp.readyState==4 && xmlhttp.status==200){var es = document.querySelectorAll(«[data-id='»+adunit+«']»);var e = Array.from(es).filter(function(e) {return !e.hasAttribute(«data-rendered»)});if(e.length > 0){e.forEach(function(el){var iframe = el.contentWindow.document;iframe.open();iframe.write(xmlhttp.responseText);iframe.close();el.setAttribute('data-rendered', true)})}}};var child=childNetworkId.trim()?','+childNetworkId.trim():'';xmlhttp.open(«GET», 'https://pubads.g.doubleclick.net/gampad/adx?iu=/147246189'+child+'/'+adunit+'&sz='+encodeURI(size)+'&t=Placement_type%3Dserving&'+Date.now(), true);xmlhttp.send();})();

Интеллектуальная рекомендация

Функция-член swap в контейнере

Функция-член swap в контейнере В векторе контейнера пространство, занимаемое его памятью, только увеличивается, например, сначала выделяется 10 000 байт, а затем стираются следующие 9 999. Хотя сущест…

Маленькое Мин яблоко

Просто смотрите этот вопрос, я не хочу это делать, я чувствую себя слишком просто. Отказ Отказ На самом деле, это также очень просто, это низкие руки. Неудачный код: #include <cstdlib> #include …

Запрос разбивки на базы данных Oracle

Например, есть такая таблица Я хочу узнать данные 3-6 Также может быть так…

Ubuntu16.04 установка записи процесса OpenCV

1. Установите зависимости и инструменты OpenCV. 2. Загрузите исходный код OpenCV и функции библиотеки и разархивируйте 3. Настройте среду Python. 4. Создайте виртуальную среду. 5. Включите виртуальную…

Весенняя загрузка + Vue Все развитие стека делает что-то внешнее знание?

axios Во-первых, Axios Instruction Axios - это проект, независимый от VUE, основанный на обещании для браузера и Node.js, HTTP-клиента Может помочь нам завершить отправку запросов AJAX в вашем браузер…

Вам также может понравиться

PostgreSQL index Простой взгляд на индекс PG Создать параллельные принципы

Это долгая длинная история, введенная из PG 8.3, в кортеже, основная роль используется для уменьшения количества ввода / вывода, необходимого для обновлений, и обновление на основе принципов на основе…

eclipse + maven настроить среду проекта SSM (для идеи)

После того, как редактор идей сам создаст новый проект maven, просто сделайте остальные следующим образом. Перед тем, как приступить к написанию учебного пособия, я создал проект maven для веб-разрабо…

124. Binary Tree Maximum Path Sum

Given a non-empty binary tree, find the maximum path sum. For this problem, a path is defined as any sequence of nodes from some starting node to any node in the tree along the parent-child …

Научите вас получать ISA за несколько простых шагов ×××

Формирование ISA ××× В последнее время в связи с бизнес-потребностями компании и реализацией в будущем резервного канала ×××, автору необходимо установить серверы &…

Массив Java

Каталог статей 1. Что такое массив 2. Определение и инициализация массива. 2.1, определение массива 2.2, статическая инициализация массива 2.3, динамическая инициализация 3. Операция с массивом 3.1, и…

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

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

Боковая панель