جی‌اس‌داک

جی‌اس‌داک

ارائهٔ اولیه	۱۹۹۹ (۱۹۹۹-}})
آخرین ویرایش	۳٫۶٫۳ (۱۵ ژوئیه ۲۰۱۹ (۲۰۱۹-15}}))
گونه	فرمت مستندات برنامه‌نویسی
فراگیرنده	فایل‌های جاوا اسکریپت
وبگاه	jsdoc.app

جی‌اس‌داک (به انگلیسی: 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 پشتیبانی می‌کند.
• مایکروسافت ویژوال استودیو، وب‌استورم و بسیاری دیگر از محیط‌های توسعه یکپارچه یا ویرایشگرهای متن، تکمیل کد و سایر کمک‌ها را بر اساس کامنت‌های جی‌اس‌داک ارائه می‌کنند.

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

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

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

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