Dartdoc: Perlu kemampuan untuk membuat dokumen API tingkat perpustakaan tanpa tag perpustakaan eksplisit.

dartdoc mendapatkan komentar dokumen untuk semua elemen dari penganalisis. Jadi penganalisis perlu dimodifikasi untuk mendukung mendapatkan komentar dokumen dari file dart sebelum deklarasi pertama.

@Sfshaza , bisakah Anda membuka masalah untuk penganalisis dan menautkannya di sini? Terima kasih!

https://github.com/dart-lang/analyzer_cli/issues/81

Setelah beberapa diskusi, aturan baru yang diusulkan lebih sederhana:

Gunakan komentar dokumen pertama yang dilampirkan ke arahan apa pun (impor, ekspor, dll.).

Perbaikan ini telah dilakukan pada penganalisa. Memutakhirkan ke paket penganalisis baru, saat ini 0.27.1+2, akan memperbaiki masalah ini.

Saya pikir ini sudah diperbaiki?

Saya tidak tahu apakah itu pernah diperbaiki.

Saya tidak melihat komentar perpustakaan untuk dokumen stagehand kecuali saya menambahkan pernyataan perpustakaan ( library stagehand; ) di atas impor. Kami menghapus pernyataan library di https://github.com/dart-lang/stagehand/pull/307 (3/2016), v1.0.2, dan saat itulah komentar perpustakaan menghilang dari dartdoc: 1.0 .2 dokumen perpustakaan , 1.0.1 dokumen perpustakaan

Anda benar, kami masih memerlukan pernyataan perpustakaan -- jika itu diperbaiki pada satu titik, itu sebelum saya mengambil alih.

Dan aku sebenarnya tidak benar sama sekali. Ini berhasil dalam tes internal dartdoc yang mengejutkan saya. Tidak tahu mengapa itu tidak berhasil dalam kasus Anda, akan memerlukan penyelidikan.

Sangat aneh. Terima kasih telah menyelidiki ini. Tolong beri tahu saya jika ada yang bisa saya bantu.

Ada pembaruan di sini?

Status AFAIK tidak berubah.

Saya pikir kami menginginkan ini: https://github.com/dart-lang/language/issues/1073

@kevmoo Perhatikan bahwa kami mengenali dan menghasilkan dokumen untuk perpustakaan, masalah ini adalah permintaan untuk memperhatikan blok komentar di awal file tanpa tag perpustakaan dan berpura-pura itu adalah komentar dokumentasi perpustakaan.

@kevmoo Perhatikan bahwa kami mengenali dan menghasilkan dokumen untuk perpustakaan, masalah ini adalah permintaan untuk memperhatikan blok komentar di awal file tanpa tag perpustakaan dan berpura-pura itu adalah komentar dokumentasi perpustakaan.

Ya. Tetapi saya menemukan banyak orang diblokir untuk memberi nama perpustakaan mereka. Jika itu bisa "telanjang" jadi kami punya tempat untuk menggantung barang – itu akan menyenangkan.

Kurang menebak untuk hal-hal seperti dartdoc dan tes

@kevmoo Solusi yang diusulkan dalam dart-lang/language#1073 (memiliki tag perpustakaan tanpa nama, misalnya library; ) adalah cara yang saya lebih suka ini diselesaikan. Tentu saja, itu berarti lebih sedikit pekerjaan untuk saya, tetapi lebih serius itu jauh lebih sedikit "lembek" dan rentan terhadap kegagalan dalam hal mengubah komentar secara tidak sengaja di header file untuk memecahkan pemetaan yang diretas. Jika ada beberapa data yang mengatakan ini adalah dampak besar kami atau jika kami memiliki pengguna kritis yang diblokir dan kami tidak bisa menunggu solusi bahasa, akan meningkatkan ke P1.

Jika Anda tidak menyertakan pernyataan perpustakaan, maka perpustakaan secara implisit dinamai sebagai nama file, bukan? Seperti main.dart akan memiliki implisit library main . Jadi mengapa pernyataan perpustakaan "kosong" tidak dapat melakukan hal yang sama?

@Levi-Lesches Tidak ada alasan khusus, selain bahasa yang perlu didukung memiliki pernyataan library; tanpa nama.

Ya, saya sangat setuju -- jadi apakah itu yang Anda harapkan dari pernyataan library; ? Sama seperti jika itu tidak ada?

Ya, saya sangat setuju -- jadi apakah itu yang Anda harapkan dari pernyataan library; ? Sama seperti jika itu tidak ada?

Dari sudut pandang saya, ini menghilangkan peretasan yang kita miliki sekarang untuk mengizinkan anotasi "mengambang" – tanpa harus memikirkan nama perpustakaan.

@Levi-Lesches Cukup banyak. Satu-satunya perbedaan adalah penganalisis akan dapat menghubungkan tidak hanya anotasi tetapi juga dokumentasi khusus untuk pernyataan itu, dan oleh karena itu mengembalikan LibraryElement s untuk konsumen alat hilir seperti dartdoc.

Deklarasi library; akan melakukan hal yang persis sama seperti tidak ada deklarasi perpustakaan, kecuali bahwa Anda dapat menggantungkan anotasi dan dartdoc di atasnya. Ini adalah deklarasi yang mewakili perpustakaan itu sendiri, seperti library foo.bar.baz; , tetapi tidak seperti yang terakhir, itu juga tidak menamai perpustakaan.

Pustaka tanpa deklarasi pustaka memiliki nama kosong, dan library; juga akan memberi pustaka nama kosong.