Sinon: Dokumentasi Gaya "Spesifikasi API"

Ngomong-ngomong, saya tidak berbicara tentang dokumentasi saat ini, yang sangat berharga. Saya hanya menyarankan hal tambahan yang komprehensif.

Java memiliki alat otomatis untuk menghasilkan JavaDocs tanpa pekerjaan manual. Untuk mencapai sesuatu seperti ini di pustaka JS membutuhkan banyak pekerjaan manual. Saya ingin melihat sesuatu seperti itu, tapi saya khawatir itu akan cepat usang.

Kami bisa bikeshed tentang anotasi kode dan sedikit perkakas. Mungkin ada opsi yang layak.

Saya tahu itu telah dibawa ke utas lain, tetapi saya pikir, sangat sederhana, bahwa seluruh perpustakaan harus didokumentasikan dengan jsDoc. Ini adalah semacam standar defacto untuk JavaScript (atau, setidaknya, argumen terkuat yang ada). Kami hanya dapat menerbitkan api yang dimulai dengan liputan dokumentasi mimimal, dan meletakkan tanda besar "dalam proses" di dinding, dan membangun dari sana.

@mantoni Ada banyak alat untuk membuat JSDocs secara otomatis. Saya tidak melihat v1 ini menjadi masalah. Anda tidak perlu membuat @typedef s di mana pun. Hanya memiliki

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

akan sedikit membantu.

Hai @ 76784 , masukan yang bagus! 😊

Namun, saya harus membuat beberapa pertimbangan.

Saya sangat suka JSDoc. Itu juga yang kami gunakan pada Chai.js dan sejauh ini berhasil dengan cukup baik karena dapat memisahkan hal-hal ke dalam ruang nama dan selalu menjaga kode tetap sinkron dengan dokumen karena mereka berada tepat di samping satu sama lain.

Namun, saya tidak setuju bahwa dokumentasi Java adalah "standar emas". Saya menemukan dokumen Java sangat kering. Ini bagus untuk referensi, tapi buruk untuk mempelajari atau membelai bagian yang lebih besar. Saya suka fakta bahwa dokumen untuk Sinon ditulis dalam gaya klasik teks biasa yang ramah. IMO yang membantu mendorong adopsi. Juga, sebagai referensi API, mereka adalah IMO yang cukup bagus.

Saya pikir akan bagus, tentu saja, memiliki JSDocs, tetapi penting untuk diperhatikan bahwa itu akan membutuhkan usaha yang sangat signifikan.

Jika @ 76784 akan memulai sebuah cabang dan menyempurnakan beberapa konsep, saya pikir beberapa orang yang tertarik pada ide tersebut dapat dengan cepat mengaitkannya dan membantu. Permukaan API tidak terlalu besar.

@tokopedia

Saya menemukan dokumen Java sangat kering. Ini bagus untuk referensi, tapi buruk untuk mempelajari atau membelai bagian yang lebih besar.

Saya tidak setuju. Saya hanya mengatakan bahwa dua hal - dokumentasi dan tutorial - harus menjadi hal yang terpisah. Kekeringan javadocs merupakan nilai tambah. Seseorang dapat pergi ke sana dan mencari tahu, melalui konvensi bahasa kering ini, _apa_ yang dilakukan "benda" itu. Dan tentu saja, yang terpenting, ini bersifat komprehensif. Saya tidak ingin struktur kalimat bertele-tele dalam dokumentasi saya - saya menginginkannya dalam tutorial saya.

Saya bukan ahli dalam JSDoc, tapi saya bertanya-tanya apakah di komentar JSDoc akan ada cara mudah untuk menautkan ke tutorial untuk entri.

Mengenai kontribusi beberapa bukti-konsep tentang ini, @ fatso83 , waktu saya agak pendek saat ini (saya tahu, siapa yang tidak?), Tetapi saya mungkin berada dalam posisi yang lebih baik untuk nanti di tahun ini . Ini akan menjadi cara yang bagus untuk mempelajari Sinon secara menyeluruh.

Masalah ini secara otomatis ditandai sebagai usang karena tidak ada aktivitas terbaru. Ini akan ditutup jika tidak ada aktivitas lebih lanjut. Terima kasih atas kontribusi Anda.

Saya telah memasang pin pada masalah ini, sehingga tidak ditutup oleh bot Stale

Jika kita memutuskan untuk menempuh jalan ini, maka saya pikir kita harus menggunakan sesuatu seperti https://github.com/gajus/eslint-plugin-jsdoc ... aturannya mungkin harus menjadi eslint-config-sinon .

Maaf untuk menyelami ini - ini benar-benar didorong oleh beberapa prioritas pekerjaan. Dan saya tidak tahu apakah ini utas yang benar, tetapi hanya untuk menawarkan umpan balik lebih lanjut tentang dokumentasi yang ada ...

Saat saya melihat sesuatu seperti mata-mata: https://sinonjs.org/releases/v7.4.1/spies/

Saya kebetulan bekerja dengan Mocha, yang memiliki sintaks berbeda dari apa yang diperlihatkan di bagian pertama.

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

    PubSub.publishSync("message");

    assertTrue(callback.called);
}

Fakta bahwa saya menggunakan Mocha daripada apapun itu (Jasmine?) Bukanlah masalah besar . Mereka jelas mirip. Tapi apa make bahwa contoh sulit untuk dipahami adalah bahwa Anda tidak menunjukkan fungsi yang sedang diuji.

Itu adalah sesuatu yang menurut saya harus dilakukan jika Anda akan memberikan contoh. Tunjukkan fungsionalitas kerja minimum dari benda apa pun yang sedang diuji. Masalah yang sama di sini, dengan myLib : https://sinonjs.org/releases/v7.4.1/fake-xhr-and-server/

Saya mengerti - myLib adalah sesuatu yang akan saya tulis. Tetapi Anda meminta banyak pemula untuk mempelajari hal-hal ini tanpa melihat apa pun yang mereka uji.

Sebenarnya tes itu IS menggunakan sintaks Mocha, Anda hanya menggunakan gaya BDD yang lebih standar (dari keduanya) :-) Ini juga digunakan bersama oleh beberapa pustaka lain, seperti Buster JS, yang juga dibuat oleh pembuat asli Sinon (bersama). Bagaimanapun, mungkin masuk akal bagi seseorang untuk memperbarui semua contoh ke gaya yang paling umum digunakan :-)

Mengenai poin-poin lainnya, ini cukup valid, dan sesuatu yang telah kita diskusikan. Sebenarnya, kami membahas tentang contoh yang dapat dijalankan, diuji, disematkan, menjamin validitas. Yang secara implisit akan memperbaiki masalah tersebut. Tapi ya, seseorang perlu duduk dan melakukannya ...

Sebenarnya tes itu IS menggunakan sintaks Mocha

Apa?? Sekarang saya harus mengoceh tentang dokumentasi Mocha. :-)

Saya sudah mencoba memulai upaya ini di https://github.com/sinonjs/samsam/pull/82. Komentar Anda diterima, silakan posting di PR itu.