Dartdoc: ``` memicu semacam penyorotan sintaks

Sebelum memperbaiki, kita perlu memeriksa berapa banyak blok yang ada dalam paket penting yang mungkin bergantung pada ini dan memigrasikannya jika perlu.

Saya pikir _sebagian besar_ kasus ``` dalam dokumen dart tidak ditentukan dengan bahasa, dalam hal ini highlight.js memilih satu dengan "deteksi bahasa otomatis." Saya akan menganggap sebagian besar kasus itu adalah contoh kode Dart, dan saya tidak yakin apa yang "dideteksi" oleh highlight.js dalam kasus itu, haha.

Ini mungkin mirip dengan perlakuan GitHub terhadap backticks non-spesifik bahasa: https://docs.github.com/en/github/writing-on-github/creating-and-highlighting-code-blocks

Cara alternatif untuk menyelesaikan ini adalah dengan mengizinkan blok yang telah diformat sebelumnya untuk menentukan teks biasa.

Ya saat ini kami memeriksa apakah tidak ada yang ditentukan lalu tambahkan Dart .

Kita dapat menambahkan penanganan untuk opsi ```plain kemudian mengatur kelas menjadi plaintext atau nohighlight sebagai gantinya .

_Benar-benar harapan saya yang sebenarnya adalah untuk menyelesaikan penyorot sintaks saya yang ditulis dalam Dart sehingga kami dapat menjalankan penyorotan selama rendering daripada pada klien dan mengontrol semuanya ..._

Saya akan baik-baik saja dengan dartdocs yang gagal jika menemukan blok ``` tanpa bahasa yang ditentukan. Default berbahaya, dan di sini menjadi eksplisit selalu lebih baik bagi orang yang membaca dokumentasi.

Ah, saya rindu kita menambahkan kelas itu di renderer. Saya baik-baik saja dengan kegagalan selama ternyata ini jarang ditemui cukup mudah untuk menangani dalam migrasi, jika tidak kita harus memiliki semacam rencana migrasi.

dartdoc sekarang memperingatkan tentang blok berpagar kode bebas bahasa, pada https://github.com/dart-lang/dartdoc/pull/2559 .

Apakah ini perubahan perilaku, atau mengkodifikasi perilaku yang ada?

Saya mendapat kesan bahwa DartDoc selalu menggunakan sintaks Dart, baik Anda menulis dart atau tidak. Apakah itu benar pada suatu saat?
Mungkin hanya untuk kode indentasi, bukan kode yang diperkuat kode?

(Apakah ada dokumentasi resmi dari format DartDoc dan apa artinya? Terutama tautan kode tidak hanya ditentukan oleh penurunan harga).

Apakah ini _perubahan_ perilaku, atau mengkodifikasi perilaku yang ada?

Saya mendapat kesan bahwa DartDoc selalu menggunakan sintaks Dart, baik Anda menulis dart atau tidak. Apakah itu benar pada suatu saat?
Mungkin hanya untuk kode indentasi, bukan kode yang diperkuat kode?

Sedikit dari keduanya. Dartdoc menggunakan sintaks dart secara default di blok kode, tetapi ini telah menyebabkan masalah dalam kasus di mana pengguna benar-benar bermaksud untuk menjadi plaintext (karenanya bug). Perubahan peringatan dimaksudkan untuk mendorong menjadi eksplisit, dan dukungan teks biasa akan ditambahkan sehingga ketika pengguna menginginkannya tersedia.

(Apakah ada dokumentasi resmi dari format DartDoc dan apa artinya? Terutama tautan kode tidak hanya ditentukan oleh penurunan harga).

Sayangnya, spesifikasinya belum menyusul implementasinya. Saya menulis awal sintaks untuk tautan kode sebagai bagian dari desain ulang untuk sepenuhnya mendukung metode ekstensi, di sini: https://docs.google.com/document/d/11Vzx7PjSNo55YpVEx1BBUlEUPkl6CUpHZ4gFcefBE1I/edit?resourcekey=0-xUb52CNfZwq5FLt.

Di luar catatan singkat di sini, tidak ada spesifikasi formal untuk ini atau elemen lain dari perilaku dartdoc. Bisa dibilang, harus ada. Dokumentasi ada dalam bentuk yang lebih umum di README. @parlough , kami mungkin harus memperbarui README/dokumen lain untuk memasukkan detail lebih lanjut tentang blok kode termasuk perubahan Anda.

Saya dapat melihat menambahkan beberapa dokumentasi lagi di sini dan mungkin di situs-www juga di sekitar blok kode. Setelah saya mendapatkannya saya akan cc Anda pada setiap perubahan.