Bagaimana cara mendokumentasikan API eksperimental atau tidak lengkap seperti @deprecated?

12

Apakah ada istilah yang baik yang serupa tetapi berbeda dari "mencela" yang berarti bahwa metode atau API ada dalam basis kode tetapi tidak boleh digunakan karena implementasinya tidak lengkap atau kemungkinan akan berubah? (Ya, aku tahu, metode-metode itu seharusnya tidak bersifat publik, yada yada yada. Aku tidak menciptakan situasiku, aku hanya berusaha membuat yang terbaik dari itu.)

Apa yang orang sarankan? Eksperimental, Tidak Lengkap, sesuatu yang lain?

Jika saya membuat dokumentasi javadoc untuk API ini yang masih dalam fluks, haruskah saya menggunakan tag @deprecated atau adakah konvensi yang lebih baik? Bagi saya @deprecated menyiratkan bahwa API ini sudah tua dan mekanisme pilihan yang lebih baru tersedia. Dalam situasi saya, tidak ada alternatif, tetapi beberapa metode di API belum selesai dan jadi tidak boleh digunakan. Pada titik ini saya tidak bisa menjadikannya pribadi, tetapi saya ingin memberikan peringatan yang jelas di dokumen.

documentation terminology api documentation-generation javadocs Michael Levy
sumber
Tag "Tidak Stabil" juga akan sangat membantu. Artinya akan menjadi sesuatu yang berbeda. "Ini seharusnya bekerja dengan baik tetapi kami mungkin akan membuat beberapa perubahan di masa depan".
Borjab

Jawaban:

8

Istilah yang sesuai kemungkinan besar adalah inkubator , ini adalah yang digunakan oleh Google dan Apache:

  • google-web-toolkit-inkubator

    Inkubator resmi widget dan perpustakaan untuk Google Web Toolkit ...

  • Apache Inkubator

    ... gateway untuk proyek sumber terbuka yang dimaksudkan untuk menjadi proyek Yayasan Perangkat Lunak Apache yang lengkap ...

Jika Anda melihat lebih dekat pada proyek-proyek yang disebutkan di atas, Anda mungkin memperhatikan bahwa API "eksperimental" (misalnya di GWT) cenderung memiliki nama paket "khusus" com.google.gwt.gen2. Ini untuk menghindari pencemaran API "final" masa depan yang ditujukan untuk konsumsi publik permanen - karena, Anda tahu,

"API Publik, seperti berlian, selamanya. Anda memiliki satu kesempatan untuk melakukannya dengan benar, jadi berikan yang terbaik ..." (Joshua Bloch, Cara Mendesain API yang Baik dan Mengapa Penting )

agas
sumber
2
Saya condong ke "Eksperimental" setelah melihat API seperti developer.chrome.com/extensions/experimental.html
Michael Levy
10

Saya akan menggunakan @deprecateduntuk alasan praktis semata.

Meskipun @deprecatedtidak menyampaikan makna yang tepat yang Anda inginkan, ia memiliki keuntungan yang signifikan: Java compiler memiliki dukungan bawaan untuk itu. Mengkompilasi dengan -deprecationflag memungkinkan Anda menemukan semua tempat di mana Anda mengganti metode yang sudah usang, membantu pengguna Anda menemukan kode yang mencurigakan dengan sangat cepat. Anda dapat menggunakan @deprecatedtag Javadoc untuk menjelaskan apa yang sebenarnya terjadi pada siapa saja yang peduli untuk membaca dokumentasi Anda. Di sinilah Anda bisa memberi tahu pengguna bahwa API itu eksperimental, harus digunakan dengan risiko sendiri, dan sebagainya.

dasblinkenlight
sumber
1
+1. Poin luar biasa. Memiliki dukungan bawaan sangat penting untuk bagian-bagian API seperti itu, dan mendorong para pengguna untuk melihat dokumentasi untuk memahami mengapa bagian-bagian itu ditandai sebagai didepresiasi.
Arseni Mourzenko
2
Saya condong ke arah sesuatu seperti "* @deprecated Ini adalah API eksperimental dan kemungkinan akan berubah" minimal untuk mendapatkan IDE dan dokumen untuk menyorot metode dan kemudian memiliki penjelasan singkat.
Michael Levy
Hanya ingat bahwa usang akan membuat banyak peringatan. Ini mungkin tidak seburuk kelihatannya. Diperingatkan fitur eksperimental bisa OK.
Borjab
3

Saya belum pernah melihat yang seperti ini di API lain, karena fitur eksperimental atau tidak lengkap tidak ada hubungannya dengan API publik.

Karena Anda tidak punya pilihan, cukup beri peringatan yang terlihat jelas bahwa bagian API dapat berubah.

Arseni Mourzenko
sumber
Baik. Sebagai contoh, kami memiliki: junit.org/apidocs/org/junit/experimental/package-summary.html Ngomong-ngomong, menggunakan paket itu adalah ide yang mengerikan. Setelah API tidak stabil, Anda perlu mengubah paket sehingga Anda akan memecah semua dependensi. Anotasi java akan jauh lebih baik
Borjab