ما هي الطريقة المفضلة للتعليق على كائنات وأساليب جافا سكريبت [مغلق]

Question

أنا معتاد على الأطلس حيث الطريقة المفضلة (حسب ما أعرفه) هي استخدام تعليقات xml مثل:

/// <summary>
///   Method to calculate distance between two points
/// </summary>
///
/// <param name="pointA">First point</param>
/// <param name="pointB">Second point</param>
/// 
function calculatePointDistance(pointA, pointB) { ... }

لقد كنت أبحث مؤخرًا في مكتبات جافا سكريبت التابعة لجهات خارجية أخرى وأرى بناء الجملة مثل:

/*
 * some comment here
 * another comment here
 * ...
 */
 function blahblah() { ... }

كمكافأة، يرجى إعلامي إذا كان هناك أي مولدات API لجافا سكريبت يمكنها قراءة نمط التعليق "المفضل".

Answer 1

هناك JSDoc

/**
 * Shape is an abstract base class. It is defined simply
 * to have something to inherit from for geometric 
 * subclasses
 * @constructor
 */
function Shape(color){
 this.color = color;
}

Answer 2

كلما كانت أبسط كلما كان ذلك أفضل، التعليقات جيدة، استخدمها :)

var something = 10; // My comment

/*
Lorem ipsum dolor sit amet, consectetur adipisicing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Ut enim ad minim veniam, quis nostrud exercitation ullamco
nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor
in reprehenderit in voluptate velit esse cillum dolore eu
fugiat nulla pariatur.
*/

function bigThing() {
    // ...
}

ولكن بالنسبة للمستند الذي تم إنشاؤه تلقائيًا ...

/**
 * Adds two numbers.
 * @param {number} num1 The first number to add.
 * @param {number} num2 The second number to add.
 * @return {number} The result of adding num1 and num2.
 */
function bigThing() {
    // ...
}

Answer 3

عروض ياهو YUIDoc.

إنه موثق جيدًا، ويدعمه Yahoo، وهو تطبيق Node.js.

كما أنه يستخدم الكثير من نفس بناء الجملة، لذلك لن يلزم إجراء العديد من التغييرات للانتقال من واحدة إلى أخرى.

Answer 4

حاول لصق ما يلي في ملف جافا سكريبت في Visual Studio 08 والتلاعب به:

var Namespace = {};
    Namespace.AnotherNamespace = {};

Namespace.AnotherNamespace.annoyingAlert = function(_message)
{
    /// <param name="_message">The message you want alerted two times</param>
    /// <summary>This is really annoying!!</summary>

    alert(_message);
    alert(_message);
};

التحسس وافر!

يمكن العثور على مزيد من المعلومات حول هذا (بما في ذلك كيفية الرجوع إلى ملفات جافا سكريبت الخارجية لاستخدامها في المكتبات الكبيرة). مدونة سكوت جو.

Answer 5

يتم استخدام التعليق الثلاثي في ​​المثال الأول فعليًا لأدوات توثيق XML الخارجية ودعم التحسس الذكي (في Visual Studio).لا يزال تعليقًا صالحًا ، ولكنه خاص :) تعليق Actuall "مشغل" هو // القيد الوحيد هناك هو أن يكون لخط واحد.

يستخدم المثال الثاني التعليق على النمط C والذي يسمح بالتعليق عبر أسطر متعددة أو في منتصف السطر.