Sinon: "مواصفات API" أسلوب التوثيق

بالمناسبة ، أنا لا أعزف على الوثائق الحالية ، وهي قيمة. أنا فقط أقترح شيئًا إضافيًا شاملاً.

تحتوي Java على أدوات آلية لإنشاء JavaDocs بدون عمل يدوي. لتحقيق شيء مثل هذا في مكتبة JS يتطلب الكثير من العمل اليدوي. أود أن أرى شيئًا كهذا ، لكنني أخشى أن يصبح عفا عليه الزمن بسرعة كبيرة.

يمكننا أن نتحدث قليلاً عن التعليقات التوضيحية للأكواد والأدوات. ربما هناك خيارات قابلة للتطبيق.

أعلم أنه تم طرحه على مواضيع أخرى ، لكنني أعتقد ، ببساطة شديدة ، أنه يجب توثيق المكتبة بأكملها باستخدام jsDoc. إنه شيء من المعايير الفعلية لجافا سكريبت (أو ، على الأقل ، أقوى حجة موجودة لواحد). يمكننا فقط نشر واجهة برمجة التطبيقات بدءًا من تغطية التوثيق المحاكاة ، ووضع علامة "قيد التنفيذ" كبيرة على الحائط ، والبناء من هناك.

mantoni هناك الكثير من الأدوات لتوليد JSDocs تلقائيًا. لا أرى أن الإصدار 1 من هذا يمثل مشكلة. لا تحتاج إلى إنشاء @typedef s في كل مكان. مجرد وجود

/**
  <strong i="8">@param</strong> {String} [foo] optional string
  <strong i="9">@example</strong> Create foo instance
       var foo = dooFoo('somestring') 
*/ 

من شأنه أن يساعد قليلا.

مرحبًا @ 76784 ، هذه مساهمة رائعة! 😊

ومع ذلك ، لدي بعض الاعتبارات.

أنا أحب JSDoc تمامًا. هذا أيضًا ما نستخدمه في Chai.js وقد نجح هذا الأمر جيدًا حتى الآن نظرًا لقدرتنا على فصل الأشياء في مساحات الأسماء والحفاظ دائمًا على الكود متزامنًا مع المستندات نظرًا لأنهما بجوار بعضهما البعض.

ومع ذلك ، فأنا لا أوافق على أن توثيق جافا هو "المعيار الذهبي". أجد أن مستندات Java جافة جدًا. إنها جيدة للرجوع إليها ، ولكنها سيئة للتعلم أو التهام أجزاء أكبر منها. أحب حقيقة أن مستندات Sinon مكتوبة بأسلوب كلاسيكي ودود بنص عادي. IMO التي تساعد في دفع التبني. أيضًا ، كمرجع لواجهة برمجة التطبيقات ، فهي IMO جيدة جدًا.

أعتقد أنه سيكون من الجيد ، بالطبع ، أن يكون لديك JSDocs ، لكن من المهم ملاحظة أنه سيتطلب جهدًا كبيرًا للغاية.

إذا بدأ @ 76784 فرعًا وقام يتشبثوا بها بسرعة ويساعدوا . سطح API ليس بهذا الحجم.

تضمين التغريدة

أجد أن مستندات Java جافة جدًا. إنها جيدة للرجوع إليها ، ولكنها سيئة للتعلم أو التهام أجزاء أكبر منها.

أنا لا أختلف. أنا فقط أقول إن الأمرين - التوثيق والدروس - يجب أن يكونا شيئًا منفصلاً. جفاف الجافادوكس ميزة إضافية. يستطيع المرء أن يذهب إلى هناك ويكتشف ، من خلال اصطلاح اللغة الجافة ، ماذا يفعل "الشيء". وبالطبع ، الأهم من ذلك ، أنها شاملة بطبيعتها. لا أريد بنية الجمل الملصقة في التوثيق - أريد ذلك في البرنامج التعليمي الخاص بي.

أنا لست خبيرًا في JSDoc ، لكنني أتساءل عما إذا كانت تعليقات JSDoc ستكون هناك طريقة سهلة للارتباط بالبرنامج التعليمي للإدخال.

فيما يتعلق بالمساهمة ببعض إثباتات المفهوم في هذا ، @ fatso83 ، أنا أقصر وقتًا قليلاً في الوقت الحالي (أعرف ، من ليس كذلك؟) ، لكن قد أكون في وضع أفضل في وقت لاحق من العام . ستكون طريقة رائعة لتعلم Sinon بدقة.

تم وضع علامة على هذه المشكلة تلقائيًا على أنها قديمة نظرًا لعدم وجود نشاط حديث لها. سيتم إغلاقه إذا لم يحدث أي نشاط آخر. شكرا لمساهماتكم.

لقد قمت بتثبيت هذه المشكلة ، لذا لا يتم إغلاقها بواسطة Stale bot

إذا قررنا السير في هذا الطريق ، فأعتقد أنه يجب علينا استخدام شيء مثل https://github.com/gajus/eslint-plugin-jsdoc ... ربما يجب أن تذهب القواعد إلى eslint-config-sinon .

آسف للغوص في هذا والخروج منه - إنه مدفوع حقًا ببعض أولويات العمل. ولا أعرف ما إذا كان هذا هو الموضوع الصحيح ، ولكن فقط لتقديم المزيد من الملاحظات حول الوثائق الحالية ...

عندما أنظر إلى شيء مثل الجواسيس: https://sinonjs.org/releases/v7.4.1/spies/

تصادف أنني أعمل مع Mocha ، الذي يحتوي على صيغة مختلفة عما هو معروض في الجزء الأول.

"test should call subscribers on publish": function () {
    var callback = sinon.spy();
    PubSub.subscribe("message", callback);

    PubSub.publishSync("message");

    assertTrue(callback.called);
}

حقيقة أنني أستخدم الموكا بدلاً من أي شيء (ياسمين؟) ليس بالأمر الكبير . من الواضح أنهم متشابهون. ولكن ماذا جعل هذا المثال من الصعب أن نفهم أن كنت لا تظهر الدالة التي يتم اختبارها.

هذا شيء أعتقد أنه يجب القيام به إذا كنت ستقدم أمثلة. أظهر الحد الأدنى من وظائف العمل لأي شيء يتم اختباره. نفس المشكلة هنا ، مع myLib : https://sinonjs.org/releases/v7.4.1/fake-xhr-and-server/

فهمت - myLib شيء أكتبه. لكنك تطلب من الكثير من المبتدئين أن يتعلموا هذه الأشياء دون أن يروا أيًا مما يختبرونه.

في الواقع ، هذا الاختبار هو باستخدام صيغة Mocha ، فأنت تستخدم فقط أسلوب BDD القياسي (من الاثنين) :-) وهو مشترك أيضًا من قبل بعض المكتبات الأخرى ، مثل Buster JS ، الذي أنشأه منشئ Sinon الأصلي أيضًا (بالاشتراك). على أي حال ، قد يكون من المنطقي أن يقوم شخص ما بتحديث جميع الأمثلة إلى النمط الأكثر شيوعًا في الاستخدام :-)

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

في الواقع هذا الاختبار هو استخدام صيغة Mocha

ماذا او ما؟؟ الآن سأضطر إلى الحديث عن وثائق موكا. :-)

لقد حاولت بدء هذا الجهد في https://github.com/sinonjs/samsam/pull/82. نرحب بتعليقاتكم ، يرجى نشرها على هذا العلاقات العامة.