Async: README terlalu panjang untuk npm

Ini secara tangensial terkait dengan #859 . Kami sudah lama ingin mengubah dokumen Async -- buat situs yang lebih mirip dengan dokumen Lodash.

Itu akan luar biasa, apakah Anda memerlukan bantuan untuk itu? Saya tidak tahu seberapa jauh Anda berada di #859.

Kami belum menyelesaikan strategi pembangunan yang tepat (menunggu untuk melihat bagaimana dorongan serupa untuk dokumen Lodash berhasil). Paling tidak, kami ingin menyalin dokumen untuk setiap metode ke dalam blok JSDoc di setiap file sumber (dengan tag lengkap dan informasi jenis), dengan maksud untuk menguraikannya dan membangun situs dokumentasi darinya.

@hargasinski kami pasti bisa menggunakan bantuan dengan ini. Jika Anda atau siapa pun tertarik untuk membantu memindahkan dokumen kami ke format yang kompatibel dengan jsdoc dalam kode, itu akan sangat dihargai. Saya sarankan melakukan metode ini dengan metode. Jika Anda tertarik, saya dapat membuat cabang untuk bekerja sehingga banyak orang dapat berkontribusi jika perlu

Lihatlah https://github.com/lodash/lodash/blob/master/lodash.js#L8428 -L8470 jika Anda mencari inspirasi.

Jika kami mendapatkan kode dalam keadaan yang didokumentasikan di JSDoc, saya dapat membuat situs dokumen yang mirip dengan ramdas, lazys, atau lodashs

@megaac terima kasih! Saya akan melihat bagaimana lodash melakukannya. Saya punya hari libur besok, jadi saya mungkin bisa menghabiskan banyak waktu untuk mengerjakannya. Saya akan memposting komentar tentang seberapa jauh saya mendapatkan.

Saya mungkin meremehkan jumlah waktu yang dibutuhkan, tetapi saya dapat menyelesaikan dokumentasi untuk metode pengumpulan. Saya harus bisa menyelesaikan sisanya besok setelah bekerja. Saya membuat permintaan tarik sehingga Anda dapat melihat apa yang telah saya lakukan sejauh ini, dan jika ada yang perlu diubah. Saya punya beberapa pertanyaan singkat.

1. Karena tidak ada konstruktor async , haruskah saya tetap menyertakan tag
2. @megawac Untuk situs, bagaimana sebaiknya mendokumentasikan fungsi iteratee dan callback ? Dalam readme, parameternya termasuk nama, seperti iteratee(item, callback) , tapi saya rasa ini tidak akan berfungsi dengan jsdoc. Saya telah melakukan sesuatu yang mirip dengan contoh lodash yang Anda @param , seperti Invoked with (item, callback) . The jsdoc situs menganjurkan untuk sesuatu seperti:

/**
 * Send a request.
 * <strong i="19">@param</strong> {requestCallback} cb - The callback that handles the response.
 */
Requester.prototype.send = function(cb) {
    // code
};

/**
 * This callback is displayed as a global member.
 * <strong i="20">@callback</strong> requestCallback
 * <strong i="21">@param</strong> {number} responseCode
 * <strong i="22">@param</strong> {string} responseMessage
 */

Karena tidak ada konstruktor async yang sebenarnya, haruskah saya tetap menyertakan tag

memberOf async pasti baik-baik saja. Juga, nit: perhatikan bahwa itu adalah memberOf dan bukan memberof

Untuk situs, bagaimana cara terbaik untuk mendokumentasikan fungsi iteratee dan callback? Dalam readme, parameternya termasuk nama, seperti iteratee(item, callback), tapi saya rasa ini tidak akan berfungsi dengan jsdoc.

Saya sebenarnya tidak sepenuhnya yakin, punya pemikiran @jdalton? Saya tahu ramda mendokumentasikannya dengan tag @sig

Juga jangan terburu-buru dalam hal ini sama sekali, ini jelas merupakan tugas besar itulah sebabnya kami terus melakukannya. Terima kasih telah memeriksanya!

Pengurai dokumen biasanya menangani bit itu. Jika tidak, mereka harus memberikan output yang diuraikan untuk Anda rekonstruksi.

Apakah mungkin untuk dengan mudah menautkan (misalnya) mapLimit dan mapSeries ke map ? Yang harus Anda katakan adalah bahwa itu adalah versi terbatas konkurensi. Kalau tidak, akan ada banyak dokumen dan contoh yang digandakan. (Saya pikir menyimpan tanda tangan tidak apa-apa)

Hei, hanya pembaruan cepat karena saya belum dapat membuat komitmen apa pun pada permintaan tarik dalam beberapa hari terakhir. Saya masih akan terus mengerjakannya. Saya memiliki sedikit pengalaman web, jadi saya juga mencari masalah pemeliharaan situs lodash . Saya akan mengunggah repositori dengan kemajuan saya setelah saya mendapatkan cukup jauh di dalamnya. Tujuannya adalah untuk mendapatkan sesuatu yang dapat digunakan async juga.

Bermain-main dengan menghasilkan dokumentasi secara lokal dengan perubahan @hargasinski (sekarang master). Saya rasa saya suka template ini http://docstrap.github.io/docstrap/. Pikiran @hargasinski & @aearly

Saya pernah menggunakan docstrap sebelumnya, saya sangat menyukainya! Ini adalah template yang bersih. Ada ide tentang tema? Preferensi saya akan cerulean atau lumen . Slate juga bagus jika Anda ingin memilih sesuatu yang lebih gelap.

Juga, apakah ini saat yang tepat untuk membahas #975? Akan lebih baik jika memiliki logo untuk situsnya

Docstrap terlihat cukup bagus. Saya merasa fitur pencarian bisa bekerja lebih baik. Tema tidak terlalu penting karena sepertinya kita dapat dengan mudah mengubahnya. (Dan kelihatannya semuanya sama, kecuali beberapa perbedaan warna, kurang lebih.)

Masih mengawasi https://github.com/lodash/lodash.github.io/issues/8 dan https://github.com/lodash/lodash.github.io/issues/15 -- karena kedua proyek tersebut menggunakan JSDoc, kita dapat menggunakan kembali strategi apa pun yang mereka adopsi.

Logo bisa menunggu, kita bisa menggunakan "Async" dalam jenis huruf yang bagus sampai ide logo yang bagus muncul. :menjulurkan lidah menutup mata:

@megawac ada karya terbaru tentang penerbitan JSDocs kami? Akan sangat bagus untuk memiliki situs dokumen sebelum rilis 2.0.

Saya bernasib buruk dengan membuat mereka membangun dan mengalami beberapa masalah saat mencoba mengkompilasi jsdocs dengan benar di mesin saya

@aearly kapan berencana melakukan rilis 2.0? @megawac Saat ini, saya tidak dapat membuat komitmen waktu, tetapi saya harus memiliki lebih banyak waktu dalam 2-3 minggu ke depan untuk membantu Anda mengerjakan ini. Jika Anda dapat membimbing saya ke arah yang benar, atau hanya membuat daftar beberapa masalah, saya dapat membantu perlahan-lahan menghilangkannya.

Kami tidak memiliki tanggal rilis -- "kapan sudah siap". Dokumen bukan persyaratan yang sulit, hanya yang bagus untuk dimiliki, karena beberapa metode baru hanya didokumentasikan melalui JSDoc.

@hargasinski terutama saya belum pernah menggunakan @jsdoc sebelumnya dan telah masalah sumber dari banyak file. Saya tidak tahu bagaimana membuat dokumen hidup di satu halaman. Masalah lain yang saya temukan adalah mendapatkan implementasi typedef ( queue dan cargo ) muncul dengan benar

Oh oke, terima kasih, saya akan membayar repo dan bermain-main dengannya sedikit, meskipun saya tidak akan bisa menyelesaikan banyak sampai akhir minggu depan. Saya akan memposting pembaruan jika saya mendapatkan sesuatu yang layak.