JSDoc

JSDoc هي لغة ترميز تُستخدم لشرح وتوثيق كود جافا سكريبت . يمكن معالجة هذه التعليقات بواسطة أدوات لإنتاج وثائق بتنسيقات مثل HTML . تم إصدار مواصفات JSDoc بموجب ترخيص CC BY-SA 3.0 ، بينما تم ترخيص مولد الوثائق ومكتبة التحليل المصاحبة لها بموجب ترخيص Apache 2.0 . ^{[ 2 ]}

تتشابه بنية ودلالات JSDoc مع بنية ودلالات Javadoc ، المستخدمة لتوثيق الشيفرة المكتوبة بلغة Java . ويختلف JSDoc عن Javadoc في كونه متخصصًا في التعامل مع السلوك الديناميكي للغة JavaScript . ^{[ 3 ]}

تم إصدار مثال مبكر يستخدم صيغة شبيهة بـ Javadoc لتوثيق جافا سكريبت في عام 1999 مع مشروع Rhino التابع لشركة Netscape / Mozilla ، وهو نظام تشغيل جافا سكريبت مكتوب بلغة جافا . وقد تضمن مولد HTML تجريبيًا باسم "JSDoc"، بإصدارات تصل إلى 1.3، كمثال على إمكانيات جافا سكريبت الخاصة به. ^{[ 4 ]}

أشرف مايكل ماثيوز على جميع الأجيال الرئيسية من "JSDoc". بدأ بـ JSDoc.pm عام 2001، وهو نظام بسيط مكتوب بلغة بيرل . لاحقًا، وبمساهمات من المبرمج الكندي غابرييل ريد، تم استضافة النظام على SourceForge في مستودع CVS . ^{[ 5 ]} مع إصدار JSDoc 1.0 (2007)، أعاد كتابة النظام بلغة جافا سكريبت (مرة أخرى لبرنامج راينو)، وبعد سلسلة من التوسعات، اكتسب JSDoc 2.0 (2008) اسم "jsdoc-toolkit". تم إصداره بموجب ترخيص MIT ، واستُضيف في مستودع Subversion على Google Code . ^{[ 6 ] بحلول عام 2011 ،} أعاد هيكلة النظام إلى JSDoc 3.0، وحذف "-toolkit" من الاسم، وغيّر الترخيص إلى ترخيص أباتشي ، واستضاف النتيجة على GitHub . يعمل الآن على Node.js. [ ^{3 ]}

بعض علامات التعليق الأكثر شيوعًا المستخدمة في JSDoc الحديثة هي:

الوسم	وصف
@author	اسم المطور
@constructor	يُحدد هذا الأمر دالة كدالة إنشاء.
@deprecated	يُشير إلى أن طريقة ما أصبحت مهملة
@exception	مرادف لـ@throws
@exports	يُحدد عضوًا يتم تصديره بواسطة الوحدة النمطية
@param	يوثق هذا الأمر مُعاملًا من مُعاملات الطريقة؛ ويمكن إضافة مُؤشر نوع البيانات بين قوسين مُعقوفين.
@private	يشير إلى أن العضو خاص
@returns	توثيق قيمة الإرجاع
@return	مرادف لـ@returns
@see	توثيق ارتباط بكائن آخر
@todo	توثيق شيء مفقود/غير مكتمل
@this	يحدد نوع الكائن الذي thisتشير إليه الكلمة المفتاحية داخل الدالة.
@throws	يوثق هذا المستند استثناءً تم طرحه بواسطة إحدى الطرق
@version	يوفر رقم إصدار المكتبة

• أداة فحص وترجمة Closure من جوجل . تقوم الأخيرة باستخراج معلومات النوع لتحسين مخرجات جافا سكريبت.
• يمكن لـ TypeScript إجراء فحص لأنواع ملفات JavaScript التي تحتوي على تعليقات JSDoc. ^{[ 7 ]} وقد حددت مايكروسوفت لغة TSDoc جديدة ذات علامات قابلة للتوسيع.
• يدعم Sublime Text برنامج JSDoc من خلال إضافة DocBlockr أو DoxyDoxygen
• تم شرح صيغة JSDoc بالتفصيل في كتاب Apress بعنوان Foundations of Ajax (ISBN). 1-59059-582-3.
• تفهم العديد من منتجات JetBrains ، مثل IntelliJ IDEA و WebStorm و NetBeans و Visual Studio Code و RubyMine، صيغة JSDoc.
• يدعم برنامج Aptana Studio المبني على Eclipse برنامج ScriptDoc.
• يستخدم محرر Mozilla المضمن JSDoc.pm.
• يستخدم إطار عمل تطبيق Helma تقنية JSDoc.
• تم إنشاء وثائق SproutCore باستخدام JSDoc.
• يوفر Visual Studio و WebStorm والعديد من بيئات التطوير المتكاملة الأخرى أو محررات النصوص ميزة إكمال التعليمات البرمجية وغيرها من المساعدات بناءً على تعليقات JSDoc.
• يدعم محرر Atom مفتوح المصدر JSDoc عبر المكون الإضافي atom-easy-jsdoc.

• مقارنة بين مولدات الوثائق
• أدوات إغلاق جوجل

• الموقع الرسمي
• jsdoc على GitHub
• "شرح جافا سكريبت لمترجم Closure" . مطورو جوجل . وثائق أدوات Closure.