**جی‌اس‌داک** (به انگلیسی: JSDoc) یک زبان نشانه گذاری است که برای کامنت‌گذاری فایل‌های کد منبع جاوااسکریپت استفاده می‌شود.

با استفاده از کامنت‌های حاوی جی‌اس‌داک، برنامه‌نویسان می‌توانند اسنادی را اضافه کنند که واسط برنامه‌نویسی کاربردی کدی را که ایجاد می‌کنند، توصیف کنند. این کامنت‌ها توسط ابزارهای مختلف برای تولید اسناد در قالب‌های قابل دسترس مانند اچ‌تی‌ام‌ال و ریچ تکست فرمت پردازش می‌شوند.

مشخصات جی‌اس‌داک تحت اجازه‌نامه کرییتیو کامنز منتشر شده‌است، در حالی که مولد مستندسازی و کتابخانه تجزیه‌کننده همراه آن نرم‌افزار آزاد و تحت مجوز آپاچی است.

تاریخچه
-------

سینتکس و معناشناسی جی‌اس‌داک شبیه به جاوادوک است که برای مستندسازی کدهای نوشته شده در زبان برنامه‌نویسی جاوا استفاده می‌شود. جی‌اس‌داک با جاواداک متفاوت است؛ زیرا برای کار کردن با رفتار پویای جاوااسکریپت، تخصص یافته‌است.

یک نمونه اولیه با استفاده از سینتکسی شبیه به جاوادوک برای مستندسازی جاوااسکریپت در سال ۱۹۹۹ به‌ همراه پروژه راینو از طرف نت‌اسکیپ و موزیلا، یک سیستم زمان اجرای جاوااسکریپت که به زبان جاوا نوشته شده‌بود، منتشر شد.

تمام نسخه‌های اصلی جی‌اس‌داک توسط مایکل ماتیوز (Michael Mathews) اداره می‌شد. او با JSDoc.pm در سال ۲۰۰۱ شروع به کار کرد، یک سیستم ساده که به زبان پرل نوشته شده‌بود. با همکاری برنامه‌نویس کانادایی گابریل رید (Gabriel Reid) در سورس‌فورج در یک مخزن سیستم نسخه‌های هم‌روند میزبانی شد. توسط جی‌اس‌داک نسخه ۱٫۰ در سال ۲۰۰۷، او سیستم را در جاوا اسکریپت بازنویسی کرد (دوباره برای پروژه راینو) و پس از مجموعه‌ای از بسط‌های جی‌اس‌داک نسخه ۲٫۰ در سال ۲۰۰۸، نام «jsdoc-toolkit» را به دست آورد، تحت پروانه ام‌آی‌تی منتشر شد و در یک مخزن کنترل نسخه در گوگل کد میزبانی شد.

تا سال ۲۰۰۱ او سیستم را به جی‌اس‌داک ۳٫۰ تغییر داد و نسخه بدست‌آمده را در گیت‌هاب قرار داد.

جی‌اس‌داک هم‌اکنون روی نود جی‌اس اجرا می‌شود.

تگ‌های جی‌اس‌داک
----------------

برخی از محبوب‌ترین تگ‌های کامنت‌نویسی مورد استفاده در جی‌اس‌داک مدرن عبارتند از:

| تگ | توضیحات |
| --- | --- |
| `@author` | نام توسعه‌دهنده |
| `@constructor` | تعریف یک تابع سازنده |
| `@deprecated` | علامت‌گذاری یک متد به‌عنوان منسوخ شده |
| `@exception` | هم‌معنی `@throws` |
| `@exports` | عضوی را که توسط ماژول ایکسپورت (صادر) شده‌است را شناسایی می‌کند |
| `@param` | یک پارامتر متد را مستند می‌کند؛ یک نشانگر نوع داده به تواند بین دو آکولاد قرار بگیرد |
| `@private` | نشان می‌دهد که یک عضو خصوصی است |
| `@returns` | یک مقدار که باید ریترن (برگشت) یابد را مستند می‌کند |
| `@return` | هم‌معنی `@returns` |
| `@see` | یک ارتباط را با یک شی دیگر، مستند می‌کند |
| `@todo` | چیزی که از دست رفته یا باز است را مستند می‌کند |
| `@this` | نوع شیئی را که کلمه کلیدی this در یک تابع به آن ارجاع می‌دهد، مشخص می‌کند. |
| `@throws` | یک استثنا (exception) را که توسط یک متد ایجاد شده‌است، مستند می‌کند |
| `@version` | یک نسخه برای کتابخانه ایجاد شده تنظیم می‌کند |

مثال
----

```
/\*\* @class Circle representing a circle. \*/
class Circle {
/\*\*
 \* Creates an instance of Circle.
 \*
 \* @author: moi
 \* @param {number} r The desired radius of the circle.
 \*/
 constructor(r) {
 /\*\* @private \*/ this.radius = r
 /\*\* @private \*/ this.circumference = 2 \* Math.PI \* r
 }

 /\*\*
 \* Creates a new Circle from a diameter.
 \*
 \* @param {number} d The desired diameter of the circle.
 \* @return {Circle} The new Circle object.
 \*/
 static fromDiameter(d) {
 return new Circle(d / 2)
 }

 /\*\*
 \* Calculates the circumference of the Circle.
 \*
 \* @deprecated since 1.1.0; use getCircumference instead
 \* @return {number} The circumference of the circle.
 \*/
 calculateCircumference() {
 return 2 \* Math.PI \* this.radius
 }

 /\*\*
 \* Returns the pre-computed circumference of the Circle.
 \*
 \* @return {number} The circumference of the circle.
 \* @since 1.1.0
 \*/
 getCircumference() {
 return this.circumference
 }

 /\*\*
 \* Find a String representation of the Circle.
 \*
 \* @override
 \* @return {string} Human-readable representation of this Circle.
 \*/
 toString() {
 return `[A Circle object with radius of ${this.radius}.]`
 }
}

/\*\*
 \* Prints a circle.
 \*
 \* @param {Circle} circle
 \*/
function printCircle(circle) {
 /\*\* @this {Circle} \*/
 function bound() { console.log(this) }
 bound.apply(circle)
}

```
توجه داشته باشید که `@class` و `@constructor` در واقع می‌توانند حذف شوند؛ زیرا سینتکس ارائه شده توسط اکمااسکریپت برای روشن‌کردن هویت آنها کافی است با این جال جی‌اس‌داک از آن استفاده می‌کند. `@override` نیز به‌طور خودکار قابل استنباط است.

موارد استفاده
-------------

* تایپ‌اسکریپت می‌تواند بررسی نوع فایل‌های جاوا اسکریپت را با حاشیه‌نویسی نوع جی‌اس‌داک انجام دهد. مایکروسافت یک زبان جدید تی‌اس‌داک با تگ‌های توسعه‌پذیر مشخص کرده‌است..
* اینتلیجی آیدیا، نت‌بینز، وی‌اس‌کد و روبی‌ماین دستور جی‌اس‌داک را می‌توانند تحلیل کنند.
* آپانتا مبتنی بر اکلیپس از ScriptDoc پشتیبانی می‌کند.
* مایکروسافت ویژوال استودیو، وب‌استورم و بسیاری دیگر از محیط‌های توسعه یکپارچه یا ویرایشگرهای متن، تکمیل کد و سایر کمک‌ها را بر اساس کامنت‌های جی‌اس‌داک ارائه می‌کنند.

جستارهای وابسته
---------------

* بسته ابزارهای گوگل

منابع
-----

1. 1 2  "JSDoc". *GitHub*. jsdoc. 4 September 2019. Retrieved 4 September 2019.
2. ↑  "Rhino example: jsdoc.js". *GitHub*. Mozilla project. May 6, 1999.
3. ↑  "JSDoc". *SourceForge* (به انگلیسی). Git conversion
4. ↑  "jsdoc-toolkit". *Google Code*. Git conversion
5. ↑  "ES 2015 Classes". *Use JSDoc*.
6. ↑  "@override". *Use JSDoc*.
7. ↑  "Type Checking JavaScript Files". *TypeScript Documentation*.

پیوند به بیرون
--------------

* وب سایت رسمی جی‌اس‌داک، برای آموزش و اسناد استفاده
* مخزن رسمی جی‌اس‌داک در گیت‌هاب، برای کدهای به‌روز

| * ن
* ب
* و
جاوااسکریپت |
| --- |
| تحلیل کد | 
* ای‌اس‌لینت
* JSHint
* جی‌اس‌لینت

 |
| مترجم | 
* کافی‌اسکریپت
* بسته ابزارهای گوگل
* ابزار وب گوگل
* Morfik
* تایپ‌اسکریپت

 |
| مفاهیم | 
* ای‌جکس
* جاوااسکریپت
* اچ‌تی‌ام‌ال پویا
* کتابخانه جاوا اسکریپت
* قواعد جاوااسکریپت
* جاوااسکریپت محجوب

 |
| اشکال‌یاب‌ها | 
* فایرباگ
* Microsoft Script Debugger
* Microsoft Script Editor
* مایکروسافت ویژوال استودیو
* Opera Dragonfly
* Microsoft Visual Web Developer Express
* Venkman
* سافاری (مرورگر)

 |
| مولد مستندسازی | 
* جی‌اس‌داک

 |
| ویرایشگرها | 
* جاوااسکریپت
* Comparison of JavaScript-based source code editors

 |
| موتورها | 
* Comparison of layout engines
* List of ECMAScript engines
* List of JavaScript engines

 |
| چارچوب نرم‌افزار | 
* Comparison of JavaScript frameworks
* List of JavaScript libraries

 |
| زبان‌های مرتبط | 
* اکشن‌اسکریپت
* asm.js
* کافی‌اسکریپت
* دارت
* اکما اسکریپت
* JavaScript OSA
* جی‌اسکریپت
* تایپ‌اسکریپت
* وی‌بی‌اسکریپت

 |
| فناوری مرتبط | 
* شیوه‌نامه آبشاری
* مدل شی‌گرای سند
* اچ‌تی‌ام‌ال
* جی‌سن

 |
| منابع | 
* ان‌پی‌ام
* نوگت

 |
| جاوااسکریپت | 
* صفحه‌های سرور فعال
* CommonJS
* JSGI
* نود.جی‌اس
* Wakanda

 |
| آزمایش واحد | 
* جزمین
* QUnit
* List of JavaScript unit testing frameworks

 |
| افراد | 
* داگلاس کراکفرد
* برندان ایچ
* جان رزایگ

 |