Ответ 1
Этот стиль комментариев для JSDoc.
Он похож на JavaDoc, но имеет некоторые отличия.
Вы можете узнать больше на https://github.com/jsdoc/jsdoc
Комментарии к блогам Netbeans
Недавно я обнаружил, что Netbeans действительно любит комментарии javascript, которые отформатированы следующим образом:
/**
* This is a sample comment
*
* @param {Number} myParam info about this parameter
* @return {String} Returns some sample string.
*/
function sample(info) { .. }
Это, кажется, совместимые с Javadoc комментарии, но так ли? Есть ли где-нибудь ресурс, который определяет, какое форматирование допустимо? Кроме того, этот стиль комментирования является общим для других IDE, таких как Eclipse?
Изменить: я загрузил этот снимок экрана, чтобы проиллюстрировать, как Netbeans интерпретирует @param и @return
Спасибо.
Ответы
Ответ 2
Теги комментариев похожи на JSDoc3, но не все теги JSDoc3 поддерживаются. Некоторые теги отсутствуют в JSdocs 3 (у них нет ссылок в списке ниже).
Вы можете видеть, какие из них доступны следующим образом:
- запустите комментарий с помощью /** и нажмите Enter;
- внутри типа комментария @;
- завершение кода вызова после знака @с помощью Ctrl + Space (Netbeans).
Он покажет вам список поддерживаемых тегов и поможет с его синтаксисом (автозаполнение параметров). Ожидается, что в будущих выпусках Netbeans будут поддерживаться новые теги, поскольку пользователи получают несколько отчетов об ошибках.
Вот список поддерживаемых тегов, как для Netbeans 7.4:
- @argument
// Define argument type, name and description. - @augments
// This object adds onto a parent object. - @author
// Identify the author of an item. - @borrows
// This object uses something from another object. - @class
// Use the following text to describe the entire class. - @constant
// Document an object as a constant. - @constructor
// This function is intended to be called with the "new" keyword. - @constructs
// This function member will be the constructor for the previous class. - @default
// Document the default value. - @устарело
// Document that this is no longer the preferred way. - @description
// Describe a symbol. - @extends
// Type object is inherited from. - @field
// A field. - @fileoverview
// Describe a file. - @function
// A function. - @игнорировать
// [todo] Remove this from the final output. - @internal
// Document an inner object. - @lends
// Document properties on an object literal as if they belonged to a symbol with a given name. - @link
// Inline tag - create a link. - @memberof
// This symbol belongs to a parent symbol. - @name
// Document the name of an object. - @namespace
// Document a namespace object. - @param
// Document the parameter to a function. - @private
// This symbol is meant to be private. - @property
// Document a property of an object. - @public
// This symbol is meant to be public. - @требует
// This file requires a JavaScript module. - @return
// Return. - @возвращает
// Document the return value of a function. - @see
// Refer to some other documentation for more information. - @since
// When was this feature added? - @static
// Document a static member. - @syntax
// Explain a syntax. - @throws
// Describe what errors could be thrown. - @type
// Document the type of an object. - @version
// Documents the version number of an item.
Ответ 3
В целом стандарты документации устанавливаются вашей организацией или клиентом. Если нет, я обычно придерживаюсь общего стандарта, аналогичного тому, что вы найдете в netbeans.
Ответ 4
Это не имеет значения. Прокомментировано все между /* и */. Netbeans просто заставляет его выглядеть лучше, добавляя * в каждой строке. Точка, в Java и Javascript, вы можете прокомментировать либо /* ... */ -multiline, либо через // ... -раздельную строку, тогда как в CSS, например, вы можете использовать только /* ... */.