블록 태그
(동의어: @virtual)이 멤버는 상속자에 의해 구현(또는 재정의)되어야 합니다.
/**
* Check whether the dairy product is solid at room temperature.
* @abstract
* @return {boolean}
*/
DairyProduct.prototype.isSolid = function() {
throw new Error('must be implemented by subclass!');
};멤버의 엑세스 수준을 말한다. pulbic, package, protected, private와 같이 쓴다.
@access + 접근제어자는 @접근제어자 로 대체가 가능하다.
/** @constructor */
function Thingy() {
/** @access private */
var foo = 0;
/** @access protected */
this._bar = 1;
/** @access package */
this.baz = 2;
/** @access public */
this.pez = 3;
}
// same as...
/** @constructor */
function OtherThingy() {
/** @private */
var foo = 0;
/** @protected */
this._bar = 1;
/** @package */
this.baz = 2;
/** @public */
this.pez = 3;
}
멤버가 다른 이름을 가진 것처럼 멤버에 대한 모든 참조를 처리하도록 한다.
내부 함수 내에서 클래스를 정의할 때 특히 유용합니다
Klass('trackr.CookieManager',
/**
* @class
* @alias trackr.CookieManager
* @param {Object} kv
*/
function(kv) {
/** The value. */
this.value = kv;
}
);
함수가 비동기임을 나타낸다.
콜백을 제공하는 함수와 같은 다른 유형의 비동기 함수에는 이 태그를 사용하지 않는다.
이 태그는 JSDoc 3.5.0 이상에서 사용할 수 있다.
일반적으로 JSDoc은 자동으로 비동기 함수를 감지하고 생성된 문서에서 이를 식별하기 때문에 이 태그를 사용할 필요가 없다.
그러나 코드에 나타나지 않는 비동기 함수에 대한 가상 주석을 작성하는 경우 이 태그를 사용하여 함수가 비동기임을 JSDoc에 알릴 수 있습니다.
/**
* Download data from the specified URL.
*
* @async
* @function downloadData
* @param {string} url - The URL to download from.
* @return {Promise<string>} The data from the URL.
*/
(동의 태그 @extends태그)
@augments는 기호가 상위 기호에서 상속되고 잠재적으로 상위 기호에 추가됨을 나타낸다.
이 태그를 사용하여 클래스 기반 및 프로토타입 기반 상속을 모두 문서화할 수 있다.
/**
* @constructor
*/
function Animal() {
/** Is this animal alive? */
this.alive = true;
}
/**
* @constructor
* @augments Animal
*/
function Duck() {}
Duck.prototype = new Animal();
/** What do ducks say? */
Duck.prototype.speak = function() {
if (this.alive) {
alert('Quack!');
}
};
var d = new Duck();
d.speak(); // Quack!
d.alive = false;
d.speak(); // (nothing)
항목의 작성자를 식별합니다.
JSDoc 3.2 이상에서 작성자 이름 뒤에 꺾쇠 괄호로 묶인 이메일 주소가 오는 경우 기본 템플릿은 이메일 주소를 mailto:링크로 변환합니다.
/**
* @author Jane Smith <jsmith@example.com>
*/
function MyClass() {}
문서에 다른 기호에 대한 문서를 추가할 수 있습니다.
이 태그는 함수를 참조하는 방법이 두 가지 이상 있지만 동일한 문서를 두 곳에 복제하고 싶지 않은 경우에 유용합니다.
/**
* @namespace
* @borrows trstr as trim
*/
var util = {
trim: trstr
};
/**
* Remove whitespace from around a string.
* @param {string} str
*/
function trstr(str) {
}
콜백의 매개변수 및 반환 값을 포함하여 다른 함수에 전달할 수 있는 콜백 함수에 대한 정보를 제공합니다.
/**
* @class
*/
function Requester() {}
/**
* Send a request.
* @param {Requester~requestCallback} cb - The callback that handles the response.
*/
Requester.prototype.send = function(cb) {
// code
};
/**
* This callback is displayed as part of the Requester class.
* @callback Requester~requestCallback
* @param {number} responseCode
* @param {string} responseMessage
*/
요즘엔 @class보다 동의어@constructor 많이 사용한다.
@class 태그는 인스턴스를 반환하기 위해 new 키워드로 호출되는 생성자로 함수를 표시합니다.
/**
* Creates a new Person.
* @class
*/
function Person() {
}
var p = new Person();
생성자 함수의 설명과 별도로 클래스에 대한 설명을 제공하는 데 사용됩니다.
JSDoc 3의 @classdesc 태그 기능은 이전 버전의 @class 기능과 중복됩니다
/**
* This is a description of the MyClass constructor function.
* @class
* @classdesc This is a description of the MyClass class.
*/
function MyClass() {
}버전 3부터 @class 태그의 구문 및 기능은 이제 @constructor 태그와 정확히 일치하며
@classdesc 태그는 클래스의 설명을 문서화하는 목적을 보다 명시적으로 전달합니다.
(동의어 @const)
문서가 상수인 기호에 속하는 것으로 표시하는 데 사용됩니다.
/** @constant
@type {string}
@default
*/
const RED = 'FF0000';
/** @constant {number} */
var ONE = 1;위 예제에서는 문자열 상수를 문서화하고 있습니다.
코드에서 const키워드를 사용하고 있지만 JSDoc에서는 필요하지 않습니다.
JavaScript 호스트 환경이 아직 상수 선언을 지원하지 않는 경우
@const 문서를 var 선언에 효과적으로 사용할 수 있습니다.
객체 리터럴을 사용하여 클래스를 정의할 때
@constructs 태그를 사용하면 특정 함수가 해당 클래스의 인스턴스를 구성하는 데 사용될 것임을 문서화할 수 있습니다.
@lends와 함께 @constructs 태그 사용
var Person = makeClass(
/** @lends Person.prototype */
{
/** @constructs */
initialize: function(name) {
this.name = name;
},
/** Describe me. */
say: function(message) {
return this.name + " says: " + message;
}
}
);
@lends가 없으면 클래스 이름을 제공해야 합니다.
makeClass('Menu',
/**
* @constructs Menu
* @param items
*/
function (items) { },
{
/** @memberof Menu# */
show: function(){
}
}
);
일부 저작권 정보를 문서화한다.
이 태그를 @file 태그 와 함께 사용한다.
/**
* @file This is my cool script.
* @copyright Michael Mathews 2011
*/
(동의어: @defaultvalue)
기본값을 문서화한다.
이 태그에 값을 직접 제공하거나 JSDoc이 소스 코드의 값을 자동으로 문서화하도록 허용할 수 있습니다.
/**
* @constant
* @default
*/
const RED = 0xff0000;
(동의어: @desc )
코드에서 더 이상 사용되지 않는 기호를 표시합니다.
deprecated 어학사전 뜻 : 중요도가 떨어져 더 이상 사용되지 않고 앞으로는 사라지게 될 (컴퓨터 시스템 기능 등)
/**
* @deprecated since version 2.0
*/
function old() {
}
관련 속성 모음을 문서화합니다.
값이 모두 동일한 유형인 정적 속성 모음을 문서화합니다.
enum은 일반적으로 상수 모음을 나타내므로 이 태그는 @readonly와 함께 사용되는 경우가 많습니다.
/**
* Enum for tri-state values.
* @readonly
* @enum {number}
*/
var triState = {
/** The true value */
TRUE: 1,
FALSE: -1,
/** @type {boolean} */
MAYBE: true
};
이벤트를 문서화합니다.
일반적인 이벤트는 정의된 속성 집합이 있는 개체로 표시됩니다.
@event 태그를 사용하여 특정 유형의 이벤트를 정의한 후에는
@fires 태그를 사용하여 메서드가 해당 이벤트를 발생시킬 수 있음을 나타낼 수 있습니다.
@listens 태그를 사용하여 기호가 이벤트를 수신함을 나타낼 수도 있습니다.
함수 호출을 이벤트로 문서화
/**
* Throw a snowball.
*
* @fires Hurl#snowball
*/
Hurl.prototype.snowball = function() {
/**
* Snowball event.
*
* @event Hurl#snowball
* @type {object}
* @property {boolean} isPacked - Indicates whether the snowball is tightly packed.
*/
this.emit('snowball', {
isPacked: this._snowball.isPacked
});
};
JSDoc 3은 @event doclet을 사용하여 이벤트 내용을 문서화합니다.
반대로 JSDoc Toolkit 2는 @event Doclet을 사용하여 동일한 이름의 이벤트가 발생할 때 실행할 수 있는 함수를 식별했습니다.
Doclet은 javadoc 툴의 내용과 출력 형식을 기술하기위하여 Doclet API를 사용하는 자바 프로그램이다.
명명된 Doclet을 사용하여 이벤트 문서화
/**
* Throw a snowball.
*
* @fires Hurl#snowball
*/
Hurl.prototype.snowball = function() {
// ...
};
/**
* Snowball event.
*
* @event Hurl#snowball
* @type {object}
* @property {boolean} isPacked - Indicates whether the snowball is tightly packed.
*/
문서화된 항목을 사용하는 방법의 예를 제공한다
이 태그 뒤에 오는 텍스트는 강조 표시된 코드로 표시된다.
캡션이 있는 예제 문서화
/**
* Solves equations of the form a * x = b
* @example <caption>Example usage of method1.</caption>
* // returns 2
* globalNS.method1(5, 10);
* @returns {Number} Returns the value of x for the equation.
*/
globalNS.method1 = function (a, b) {
return b / a;
};JavaScript 모듈에서 내보낸 멤버를 식별한다.
특별한 "exports" 객체를 사용하는 모듈에서는 @exports 태그가 필요하지 않다.
JSDoc은 이 객체의 멤버가 내보내지고 있음을 자동으로 인식한다.
마찬가지로 JSDoc은 Node.js 모듈의 특수 "module.exports" 속성을 자동으로 인식합니다.
CommonJS 모듈
/**
* A module that says hello!
* @module hello/world
*/
/** Say hello. */
exports.sayHello = function() {
return 'Hello world';
};Node.js 모듈
/**
* A module that shouts hello!
* @module hello/world
*/
/** SAY HELLO. */
module.exports = function() {
return "HELLO WORLD";
};
(동의어: @host)
현재 패키지 외부에 정의된 클래스, 네임스페이스 또는 모듈을 식별한다.
이 태그를 사용하여 외부 기호에 대한 패키지 확장을 문서화하거나 외부 기호에 대한 정보를 패키지 사용자에게 제공할 수 있다.
다음 예제는 String 새 인스턴스 메소드와 함께 내장 객체를 외부 객체로 문서화하는 방법을 보여준다external:String#rot13.
/**
* The built in string object.
* @external String
* @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String|String}
*/
/**
* Create a ROT13-encoded version of the string. Added by the `foo` package.
* @function external:String#rot13
* @example
* var greeting = new String('hello world');
* console.log( greeting.rot13() ); // uryyb jbeyq
*/
(동의어: @fileoverview, @overview)
파일을 대한 설명을 제공한다.
파일 시작 부분의 JSDoc 주석에 태그를 사용한다.
/**
* @file Manages the configuration settings for the widget.
* @author Rowina Sanela
*/
(동의어: @emits)
이 메서드가 실행할 수 있는 이벤트를 설명합니다.
@event 태그 와 같이 사용하여 이벤트 내용을 문서화합니다.
/**
* Drink the milkshake.
*
* @fires Milkshake#drain
*/
Milkshake.prototype.drink = function() {
// ...
};
(동의어: @func, @method)
함수의 기능이나 방법을 설명한다.
@function을 사용하여 함수를 표시한다.
/** @function */
var paginate = paginateFactory(pages);
@name과 함께 @function 사용한다.
/** @function myFunction */
// the above is the same as:
/** @function
* @name myFunction */
함수가 생성기 함수임을 나타낸다.
즉 , 구문을 사용하여 선언되었음을 의미합니다
function* foo() {}. 이 태그는 JSDoc 3.5.0 이상에서 사용할 수 있습니다.
일반적으로 JSDoc은 생성기 함수를 자동으로 감지하고 생성된 문서에서 식별하므로 이 태그를 사용할 필요가 없습니다.
그러나 코드에 나타나지 않는 생성기 함수에 대한 가상 주석을 작성하는 경우
이 태그를 사용하여 함수가 생성기 함수임을 JSDoc에 알릴 수 있습니다.
@generator 태그가 있는 가상 댓글
/**
* Generate numbers in the Fibonacci sequence.
*
* @generator
* @function fibonacci
* @yields {number} The next number in the Fibonacci sequence.
*/
전역 개체를 문서화합니다.
JSDoc은 소스 파일 내에서 기호의 실제 범위를 무시합니다.
이 태그는 로컬로 정의된 다음 전역 기호에 할당된 기호에 특히 유용합니다.
내부 변수를 전역 변수로 문서화
(function() {
/** @global */
var foo = 'hello foo';
this.foo = foo;
}).apply(window);
생성자를 표시하지 않아야 함을 나타냅니다.
이 태그는 JSDoc 3.5.0 이상에서 사용할 수 있습니다.
ES2015 이전 클래스의 경우 이 태그를 @class또는 @constructor 태그 와 함께 사용한다.
ES2015 클래스의 경우 생성자의 JSDoc 주석에서 이 태그를 사용하십시오.
클래스에 명시적 생성자가 없는 경우 클래스에 대한 JSDoc 주석에서 @hideconstructor를 사용한다.
ES2015 클래스가 포함된 @hideconstructor 태그
/**
* Waffle iron singleton.
*/
class WaffleIron {
#instance = null;
/**
* Create the waffle iron.
*
* @hideconstructor
*/
constructor() {
if (#instance) {
return #instance;
}
/**
* Cook a waffle.
*
* @param {Batter} batter - The waffle batter.
* @return {Waffle} The cooked waffle.
*/
this.cook = function(batter) {};
this.#instance = this;
}
/**
* Get the WaffleIron instance.
*
* @return {WaffleIron} The WaffleIron instance.
*/
getInstance() {
return new WaffleIron();
}
}
문서에서 기호를 생략한다.
다른 모든 태그보다 우선 시 한다.
다음 예에서는 Jacket및가 Jacket#color문서에 표시되지 않습니다.
@ignore태그 가 있는 클래스
/**
* @class
* @ignore
*/
function Jacket() {
/** The jacket's color. */
this.color = null;
}
이 기호는 인터페이스(interface)를 구현한다.
다음 예제에서 TransparentColor클래스는 Color인터페이스를 구현하고 TransparentColor#rgba메서드를 추가한다.
/**
* Interface for classes that represent a color.
*
* @interface
*/
function Color() {}
/**
* Get the color as an array of red, green, and blue values, represented as
* decimal numbers between 0 and 1.
*
* @returns {Array<number>} An array containing the red, green, and blue values,
* in that order.
*/
Color.prototype.rgb = function() {
throw new Error('not implemented');
};
/**
* Class representing a color with transparency information.
*
* @class
* @implements {Color}
*/
function TransparentColor() {}
// inherits the documentation from `Color#rgb`
TransparentColor.prototype.rgb = function() {
// ...
};
/**
* Get the color as an array of red, green, blue, and alpha values, represented
* as decimal numbers between 0 and 1.
*
* @returns {Array<number>} An array containing the red, green, blue, and alpha
* values, in that order.
*/
TransparentColor.prototype.rgba = function() {
// ...
};
@inheritdoc태그는 기호가 부모 클래스에서 문서를 상속해야 함을 나타냅니다.
JSDoc 주석에 포함하는 다른 모든 태그는 무시됩니다.
부모 클래스에서 상속받은 클래스
/**
* @classdesc Abstract class representing a network connection.
* @class
*/
function Connection() {}
/**
* Open the connection.
*/
Connection.prototype.open = function() {
// ...
};
/**
* @classdesc Class representing a socket connection.
* @class
* @augments Connection
*/
function Socket() {}
/** @inheritdoc */
Socket.prototype.open = function() {
// ...
@inner 태그를 사용하면 심볼을 상위 심볼의 내부 멤버로 표시합니다.
즉, "Parent~Child"로 참조할 수 있습니다.
@inner를 사용하면 Doclet의 기본 범위를 재정의합니다(전역 범위에 있지 않은 경우 전역으로 유지됨).
@inner 사용
/** @namespace */
var MyNamespace = {
/**
* foo is now MyNamespace~foo rather than MyNamespace.foo.
* @inner
*/
foo: 1
};위의 예에서 @inner를 사용하여 네임스페이스의 구성원이 내부 구성원으로 문서화되도록 강제합니다.
이것은 이제 foo가 MyNamespace~foo대신 긴 이름을 갖는다는 것을 의미합니다.
@instance 태그를 사용하면 심볼을 상위 심볼의 인스턴스 멤버로 표시합니다.
즉, "Parent#Child"로 참조할 수 있습니다.
@instance를 사용하면 Doclet의 기본 범위를 재정의합니다(전역 범위에 있지 않은 경우 전역으로 유지됨).
@instance를 사용하여 인스턴스 구성원 식별
/** @namespace */
var BaseObject = {
/**
* foo is now BaseObject#foo rather than BaseObject.foo.
* @instance
*/
foo: null
};
/** Generates BaseObject instances. */
function fooFactory(fooValue) {
var props = { foo: fooValue };
return Object.create(BaseObject, props);
}
@interface태그는 심볼을 다른 심볼이 구현할 수 있는 인터페이스로 표시합니다.
예를 들어 코드에서 메서드와 속성이 스텁 아웃된 부모 클래스를 정의할 수 있습니다.
부모 클래스에 @interface 태그를 추가하여 자식 클래스가 부모 클래스의 메서드와 속성을 구현해야 함을 나타낼 수 있습니다.
@interface 태그 사용
/**
* Interface for classes that represent a color.
*
* @interface
*/
function Color() {}
/**
* Get the color as an array of red, green, and blue values, represented as
* decimal numbers between 0 and 1.
*
* @returns {Array<number>} An array containing the red, green, and blue values,
* in that order.
*/
Color.prototype.rgb = function() {
throw new Error('not implemented');
};
문서화되는 기호의종류 (예: 클래스 또는 모듈)를 문서화하는 데 사용됩니다.
기호의 종류 는 기호의 유형 (예: 문자열 또는 부울)과 다릅니다.
일반적으로 기호의 종류는 Doclet의 다른 태그에 의해 결정되기 때문에 @kind 태그가 필요하지 않습니다.
예를 들어
@class 태그를 사용하면 자동으로 "@kind 클래스"가 암시되고
@namespace 태그를 사용하면 "@kind 네임스페이스"가 암시됩니다.
@kind 사용
// The following examples produce the same result:
/**
* A constant.
* @kind constant
*/
const asdf = 1;
/**
* A constant.
* @constant
*/
const asdf = 1;
주어진 이름을 가진 기호에 속하는 것처럼 개체 리터럴의 속성을 문서화합니다.
생성자로 문서화
var Person = makeClass(
/** @lends Person.prototype */
{
/**
* Create a `Person` instance.
* @constructs
* @param {string} name - The person's name.
*/
initialize: function(name) {
this.name = name;
},
/**
* Say something.
* @param {string} message - The message to say.
* @returns {string} The complete message.
*/
say: function(message) {
return this.name + " says: " + message;
}
}
);
클래스 프레임워크는 대여된 initialize 함수를 사용하여 person 인스턴스를 구성하지만
person 인스턴스에는 자체 initialize method가 없다. 해결책은 @constructs 태그를 에 추가하는 것이다.
이 코드에 적용되는 라이선스를 식별합니다.
Apache License 2.0에 따라 배포되는 모듈
/**
* Utility functions for the foo package.
* @module foo/util
* @license Apache-2.0
*/
기호가 수신하는 이벤트를 나열합니다.
이벤트 및 리스너 문서화
다음 예제에서는 module:hurler~event:snowball라는 이벤트 와
이벤트를 수신하는 module:playground/monitor.reportThrowage라는 메서드 를 문서화하는 방법을 보여줍니다.
define('hurler', [], function () {
/**
* Event reporting that a snowball has been hurled.
*
* @event module:hurler~snowball
* @property {number} velocity - The snowball's velocity, in meters per second.
*/
/**
* Snowball-hurling module.
*
* @module hurler
*/
var exports = {
/**
* Attack an innocent (or guilty) person with a snowball.
*
* @method
* @fires module:hurler~snowball
*/
attack: function () {
this.emit('snowball', { velocity: 10 });
}
};
return exports;
});
define('playground/monitor', [], function () {
/**
* Keeps an eye out for snowball-throwers.
*
* @module playground/monitor
*/
var exports = {
/**
* Report the throwing of a snowball.
*
* @method
* @param {module:hurler~event:snowball} e - A snowball event.
* @listens module:hurler~event:snowball
*/
reportThrowage: function (e) {
this.log('snowball thrown: velocity ' + e.velocity);
}
};
return exports;
});
(동의어: @var)
"class", "function" 또는 "constant"와 같이 더 특수화된 종류가 없는 모든 멤버를 식별합니다.
Data#point와 함께 @member 사용
/** @class */
function Data() {
/** @member {Object} */
this.point = {};
}다음은 (가상) 변수 'foo'를 문서화하기 위해 @member의 동의어인 @var를 사용하는 예입니다.
@var를 사용하여 가상 멤버 문서화
/**
* A variable in the global namespace called 'foo'.
* @var {number} foo
*/
위의 예는 다음과 동일합니다.
/**
* A variable in the global namespace called 'foo'.
* @type {number}
*/
var foo;
상위 기호에 속하는 멤버 기호를 식별합니다.
기본적으로 @memberof 태그는 멤버 기호를 정적 멤버로 문서화합니다
@memberof 사용
/** @namespace */
var Tools = {};
/** @memberof Tools */
var hammer = function() {
};
Tools.hammer = hammer;
믹스인 개체를 문서화합니다.
@mixin의 예
/**
* This provides methods used for event handling. It's not meant to
* be used directly.
*
* @mixin
*/
var Eventful = {
/**
* Register a handler function to be called whenever this event is fired.
* @param {string} eventName - Name of the event.
* @param {function(Object)} handler - The handler to call.
*/
on: function(eventName, handler) {
// code...
},
/**
* Fire an event, causing all handlers for that event name to run.
* @param {string} eventName - Name of the event.
* @param {Object} eventData - The data provided to each handler.
*/
fire: function(eventName, eventData) {
// code...
}
};
이 개체는 다른 개체의 모든 구성원을 혼합합니다.
@mixes 태그 사용
/**
* @constructor FormButton
* @mixes Eventful
*/
var FormButton = function() {
// code...
};
FormButton.prototype.press = function() {
this.fire('press', {});
}
mix(Eventful).into(FormButton.prototype);이제 FormButton 클래스를 추가하고 모든 Eventful 함수를 FormButton에 혼합하는 "mix" 함수를 호출하여 FormButton이 이벤트를 발생시키고 리스너를 가질 수 있도록 합니다.
@mixes 태그를 사용하여 FormButton이 Eventful 기능을 혼합함을 나타냅니다.
JavaScript 모듈을 문서화하십시오.
기본 @module 사용
다음 예는 모듈의 기호에 사용되는 이름 경로를 보여줍니다.
첫 번째 기호는 모듈 전용 또는 "내부" 변수로, 모듈 내에서만 액세스할 수 있습니다.
두 번째 기호는 모듈에서 내보낸 정적 함수입니다.
/** @module myModule */
/** will be module:myModule~foo */
var foo = 1;
/** will be module:myModule.bar */
var bar = function() {};
개체의 이름을 문서화합니다.
JSDoc이 모든 주변 코드를 무시하고 JSDoc 주석의 나머지 부분을 지정된 이름과 연관시키도록 강제합니다.
이 태그는 런타임 시 생성되는 메서드와 같이 코드에서 쉽게 볼 수 없는 기호에 대한 "가상 주석"에서 가장 잘 사용됩니다.
다음 예제는 @name 태그를 사용하여 JSDoc이 일반적으로 인식하지 못하는 함수를 문서화하는 방법을 보여준다.
/**
* @name highlightSearchTerm
* @function
* @global
* @param {string} term - The search term to highlight.
*/
eval("window.highlightSearchTerm = function(term) {};")
네임스페이스 개체를 문서화합니다.
@namespace 태그는 개체가 해당 멤버에 대한 네임스페이스를 생성함을 나타냅니다.
개체에 @namespace 태그 사용
/**
* My namespace.
* @namespace
*/
var MyNamespace = {
/** documented as MyNamespace.foo */
foo: function() {},
/** documented as MyNamespace.bar */
bar: 1
};
부모 클래스에서 같은 이름을 가진 기호를 재정의함을 나타냅니다.
부모를 재정의하는 메서드
/**
* @classdesc Abstract class representing a network connection.
* @class
*/
function Connection() {}
/**
* Open the connection.
*/
Connection.prototype.open = function() {
// ...
};
/**
* @classdesc Class representing a socket connection.
* @class
* @augments Connection
*/
function Socket() {}
/**
* Open the socket.
* @override
*/
Socket.prototype.open = function() {
/
이 기호는 패키지 전용을 의미합니다.
/** @constructor */
function Thingy() {
/** @package */
this._bar = 1;
}
(동의어: @arg, @argument)
매개변수를 함수에 문서화합니다.
가독성을 높이기 위해 설명 앞에 하이픈을 추가할 수 있습니다.
하이픈 앞뒤에 공백을 포함해야 합니다.
/**
* @param {string} somebody - Somebody's name.
*/
function sayHello(somebody) {
alert('Hello ' + somebody);
}
/** @namespace */
var Documents = {
/**
* An ordinary newspaper.
*/
Newspaper: 1,
/**
* My diary.
* @private
*/
Diary: 2
};(동의어: @prop)
클래스, 네임스페이스 또는 기타 개체의 정적 속성 목록을 쉽게 문서화하는 방법입니다.
/**
* @namespace
* @property {object} defaults - The default values for parties.
* @property {number} defaults.players - The default number of players.
* @property {string} defaults.level - The default level for the party.
* @property {object} defaults.treasure - The default treasure.
* @property {number} defaults.treasure.gold - How much gold the party starts with.
*/
var config = {
defaults: {
players: 1,
level: 'beginner',
treasure: {
gold: 0
}
}
};
일반적으로 이 태그는 기호가 현재 모듈 내에서만 사용 가능하거나 사용해야 함을 나타냅니다.
.JSDoc 3.3.0 이상에서는 -a/--access명령줄 옵션 을 사용하여 이 동작을 변경할 수 있습니다.
/** @constructor */
function Thingy() {
/** @protected */
this._bar = 1;
}
모든 접근이 가능하다는 문서화이다.
/**
* The Thingy class is available to all.
* @public
* @class
*/
function Thingy() {
/**
* The Thingy~foo member. Note that 'foo' is still an inner member
* of 'Thingy', in spite of the @public tag.
* @public
*/
var foo = 0;
}
읽기 전용임을 나타낸다.
/**
* A constant.
* @readonly
* @const {number}
*/
const FOO = 1;
이 코드를 사용하는 데 필요한 모듈을 문서화할 수 있습니다.
모듈 이름은 "moduleName" 또는 "module:moduleName"으로 지정한다.
/**
* This class requires the modules {@link module:xyzcorp/helper} and
* {@link module:xyzcorp/helper.ShinyWidget#polish}.
* @class
* @requires module:xyzcorp/helper
* @requires xyzcorp/helper.ShinyWidget#polish
*/
function Widgetizer() {}
(동의어: @return)
함수의 반환 값을 문서화합니다.
/**
* Returns the sum of a and b
* @param {number} a
* @param {number} b
* @returns {number} Sum of a and b
*/
function sum(a, b) {
return a + b;
}
@see 태그를 사용하면 문서화되는 것과 관련될 수 있는 다른 기호나 리소스를 참조할 수 있다.
/**
* Both of these will link to the bar function.
* @see {@link bar}
* @see bar
*/
function foo() {}
// Use the inline {@link} tag to include a link within a free-form description.
/**
* @see {@link foo} for further information.
* @see {@link http://github.com|GitHub}
*/
function bar() {}
클래스, 메서드 또는 기타 기호가 특정 버전에 추가되었음을 나타낸다.
/**
* Provides access to user information.
* @since 1.0.1
*/
function UserRecord() {}
정적 멤버를 문서화합니다.
/** @namespace MyNamespace */
/**
* @function myFunction
* @memberof MyNamespace
* @static
*/전체 설명을 요약하는 태그이다.
/**
* A very long, verbose, wordy, long-winded, tedious, verbacious, tautological,
* profuse, expansive, enthusiastic, redundant, flowery, eloquent, articulate,
* loquacious, garrulous, chatty, extended, babbling description.
* @summary A concise summary.
*/
function bloviate() {}
참조하는 객체를 나타낸다.
다음 예에서 @this 태그는 "this.name"이 "name"이라는 전역 기호가 아닌 "Greeter#name"으로 문서화되도록 합니다.
/** @constructor */
function Greeter(name) {
setName.apply(this, name);
}
/** @this Greeter */
function setName(name) {
/** document me */
this.name = name;
}
(동의어: @exception)
발생할 수 있는 오류를 설명합니다.
유형 및 설명과 함께 @throws 태그 사용
/**
* @throws {DivideByZero} Argument x must be non-zero.
*/
function baz(x) {}
코드의 일부에 대해 완료할 작업을 문서화할 수 있습니다.
/**
* @todo Write the documentation.
* @todo Implement this function.
*/
function foo() {
// write me
}
설명서와 관련된 자습서 파일에 대한 링크를 삽입한다.
/**
* Description
* @class
* @tutorial tutorial-1
* @tutorial tutorial-2
*/
function MyClass() {}
개체 유형을 문서화합니다.
/** @type {(string|Array.)} */
var foo;
/** @type {number} */
var bar = 1;
사용자 정의 유형을 문서화하는 데 유용하다..
특히 반복적으로 참조하려는 경우에 유용하다.
/**
* A number, or a string containing a number.
* @typedef {(number|string)} NumberLike
*/
/**
* Set the magic number.
* @param {NumberLike} x - The magic number.
*/
function setMagicNumber(x) {
}
같은 이름을 가진 다른 개체를 구별합니다.
/**
* The Widget namespace.
* @namespace Widget
*/
// you can also use '@class Widget(2)' and omit the @variation tag
/**
* The Widget class. Defaults to the properties in {@link Widget.properties}.
* @class
* @variation 2
* @param {Object} props - Name-value pairs to add to the widget.
*/
function Widget(props) {}
/**
* Properties added by default to a new {@link Widget(2)} instance.
*/
Widget.properties = {
/**
* Indicates whether the widget is shiny.
*/
shiny: true,
/**
* Indicates whether the widget is metallic.
*/
metallic: true
};
항목의 버전 번호를 문서화합니다.
/**
* Solves equations of the form a * x = b. Returns the value
* of x.
* @version 1.2.3
* @tutorial solver
*/
function solver(a, b) {
return b / a;
}(동의어: @yield)
생성기 함수에서 생성된 값을 문서화합니다.
JSDoc 3.5.0 이상에서 사용할 수 있다.
일반 함수를 문서화 하는 경우 @return 태그를 쓴다.
유형 및 설명이 포함된 @yields 태그
/**
* Generate the Fibonacci sequence of numbers.
*
* @yields {number} The next number in the Fibonacci sequence.
*/
function* fibonacci() {}인라인 태그
(동의어: {@linkcode}, {@linkplain})
설명서의 다른 항목에 연결합니다.
{@linkcode}: 링크의 텍스트가 모노스페이스 글꼴을 사용하도록 합니다.
{@linkplain}: 링크의 텍스트를 모노스페이스 글꼴 없이 일반 텍스트로 표시합니다.
{@link namepathOrURL}
[link text]{@link namepathOrURL}
{@link namepathOrURL|link text}
{@link namepathOrURL link text (after the first space)}
설명서 튜토리얼 링크.
/**
* See {@tutorial gettingstarted} and [Configuring the Dashboard]{@tutorial dashboard}.
* For more information, see {@tutorial create|Creating a Widget} and
* {@tutorial destroy Destroying a Widget}.
*/
function myFunction() {}'Web > javascript' 카테고리의 다른 글
| js로 동적 테이블 만들기 (0) | 2023.01.26 |
|---|---|
| 이벤트 등록 addEventListener() (0) | 2023.01.25 |
| JSDoc 개념 (0) | 2023.01.18 |
| 자바스크립트 namespace 패턴 이해하기 (0) | 2023.01.17 |
| prototype의 이해 (0) | 2023.01.16 |