Комментарии к блогам 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

Спасибо.

Ответ 1

Этот стиль комментариев для JSDoc.

Он похож на JavaDoc, но имеет некоторые отличия.

Вы можете узнать больше на https://github.com/jsdoc/jsdoc

Ответ 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, например, вы можете использовать только /* ... */.