@Deprecated gibi deneysel veya eksik API'ler nasıl belgelenir?

Bir yöntem veya API'nin kod tabanında olduğu, ancak uygulamasının tamamlanmadığı veya büyük olasılıkla değişeceği için kullanılmaması gerektiği anlamına gelen "kullanımdan kaldırma" ifadesinden farklı ancak iyi bir terim var mı? (Evet, biliyorum, bu yöntemler herkese açık olmamalı, yada yada yada. Durumumu yaratmadım, sadece en iyisini yapmaya çalışıyorum.)

İnsanlar ne önerir? Deneysel, Eksik, başka bir şey?

Hala akıta olan bu API için javadoc belgeleri oluşturuyorsanız, @deprecated etiketini kullanmalı mıyım yoksa daha iyi bir kural var mı? @Deprecated bana göre bu API'nın eski olduğunu ve daha yeni bir tercih edilen mekanizmanın mevcut olduğunu ima ediyor. Benim durumumda, alternatif yok, ancak API'deki bazı yöntemler bitmedi ve bu yüzden kullanılmamalıdır. Bu noktada onları özel yapamıyorum, ancak dokümanlara net uyarılar koymak istiyorum.

Uygun terim büyük olasılıkla kuluçka makinesi , bu Google ve Apache tarafından kullanılan bir terimdir :

• hakkında-web araç-inkübatör

  Google Web Araç Seti için widget ve kitaplıkların resmi kuluçka makinesi ...

• Apache İnkübatörü

  ... tam teşekküllü Apache Yazılım Vakfı projeleri olmayı amaçlayan açık kaynaklı projelerin geçidi ...

Yukarıda belirtilen projelere daha yakından bakarsanız, "deneysel" API'lerin (örn. GWT'de) "özel" paket adlarına sahip olma eğiliminde olduğunu fark edebilirsiniz com.google.gwt.gen2. Bunun amacı, sürekli kamu tüketimine yönelik gelecekteki "kesinleşmiş" API'yi kirletmekten kaçınmaktır - çünkü,

"Elmaslar gibi herkese açık API'lar sonsuza dek. Doğru bir şansınız var, bu yüzden elinizden gelenin en iyisini yapın ..." (Joshua Bloch, İyi Bir API Nasıl Tasarlanır ve Neden Önemlidir )

Ben kullanacağı @deprecatedtamamen pratik nedenlerle.

Her ne kadar @deprecatedsen istediğini tam olarak ne anlama vermemektedir, bu önemli bir avantaja sahiptir: Java derleyicisi yerleşik bunun için destek. -deprecationBayrakla derlemek, kullanımdan kaldırılmış bir yöntemi geçersiz kıldığınız tüm yerleri bulmanıza olanak tanır ve kullanıcılarınızın şüpheli kodu çok hızlı bir şekilde bulmalarına yardımcı olur. @deprecatedBelgelerinizi okumak isteyen herkese neler olup bittiğini açıklamak için Javadoc etiketini kullanabilirsiniz . Bu, kullanıcıya API'nin deneysel olduğunu, kendi sorumluluğunda kullanılması gerektiğini söyleyebileceğiniz yerdir.

Deneysel veya eksik özelliklerin herkese açık bir API'da hiçbir ilgisi olmadığından, diğer API'larda böyle bir şey görmedim.

Seçimleriniz olmadığından, API'nın bir bölümünün değişebileceğine dair açıkça görünür bir uyarı verin.