NetBeans комментарии JavaScript

Question

Я недавно обнаружил, что 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

Спасибо.

Answer 1

Теги комментариев похожи на JSDoc3, но поддерживаются не все теги JSDoc3.Некоторые теги отсутствуют в JSdocs 3 (они не имеют ссылок в списке ниже).

Вы можете увидеть, какие из них доступны следующим образом:

• начать комментарий с / ** инажмите Enter;
• внутри комментария типа @;
• завершение кода вызова после знака @ с помощью Ctrl + Пробел (Netbeans).

Появится списокподдерживаемых тегов и справка по его синтаксису (параметры автозаполнения).Ожидается, что в будущих выпусках Netbeans будет поддерживаться больше тегов, поскольку пользователи выпускают несколько отчетов об ошибках.

Вот список поддерживаемых тегов для Netbeans 7.4:

• @ аргумент // Define argument type, name and description.
• @ augments // This object adds onto a parent object.
• @ author // Identify the author of an item.
• @ займ // 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.
• @ ignore // [todo] Remove this from the final output.
• @ inner // 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.
• @ Returns // Document the return value of a function.
• @ см. // Refer to some other documentation for more information.
• @ с // When was this feature added?
• @ static // Document a static member.
• @ синтаксис // 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.

Answer 2

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

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

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

Answer 3

Как правило, стандарты документации устанавливаются вашей организацией или клиентом.Если нет, то я склонен следовать общему стандарту, аналогичному тому, который вы найдете в netbeans.

Answer 4

Это не имеет значения. Все между /* и */ комментируется. Netbeans просто улучшает внешний вид, добавляя * в каждую строку. Дело в том, что в Java и Javascript вы можете комментировать либо /* ... */ -много или однострочно // ..., тогда как в CSS, например, вы можете использовать только /* ... */.