Come documentare API sperimentali o incomplete come @deprecated?

Esiste un buon termine simile ma diverso da "deprecato" per indicare che un metodo o API è nella base di codice ma non deve essere utilizzato perché la sua implementazione non è completa o probabilmente cambierà? (Sì, lo so, quei metodi non dovrebbero essere pubblici, yada yada yada. Non ho creato la mia situazione, sto solo cercando di trarne il meglio.)

Cosa suggeriscono le persone? Sperimentale, incompleto, qualcos'altro?

Se sto compilando la documentazione javadoc per questa API ancora in evoluzione, dovrei usare il tag @deprecated o esiste una convenzione migliore? Per me @deprecated implica che questa API è vecchia e che è disponibile un nuovo meccanismo preferito. Nella mia situazione, non ci sono alternative, ma alcuni dei metodi nell'API non sono finiti e quindi non dovrebbero essere usati. A questo punto non posso renderli privati, ma vorrei mettere chiari avvertimenti nei documenti.

Il termine appropriato è molto probabilmente incubatore , questo è quello usato da Google e Apache:

• google-web-toolkit-incubatore

  L'incubatore ufficiale di widget e librerie per Google Web Toolkit ...

• Incubatrice di Apache

  ... il gateway per i progetti open source destinati a diventare progetti a pieno titolo Apache Software Foundation ...

Se dai un'occhiata più da vicino ai progetti di cui sopra, potresti notare che le API "sperimentali" (ad esempio in GWT) tendono ad avere nomi di pacchetti "dedicati", come com.google.gwt.gen2. Questo per evitare di inquinare l'API "finalizzata" futura destinata al consumo pubblico permanente, perché, sai,

"Le API pubbliche, come i diamanti, sono per sempre. Hai una possibilità per farlo nel modo giusto, quindi dai il meglio di te ..." (Joshua Bloch, How to Design a Good API e Why it Matters )

Vorrei usare @deprecatedper motivi puramente pratici.

Sebbene @deprecatednon trasmetta il significato esatto che desideri, ha un vantaggio significativo: il compilatore Java ha il supporto integrato per esso. La compilazione con -deprecationflag ti consente di trovare tutti i luoghi in cui esegui l'override di un metodo obsoleto, aiutando i tuoi utenti a trovare molto rapidamente il codice sospetto. Puoi usare il @deprecatedtag Javadoc per spiegare cosa sta realmente succedendo a chiunque si preoccupi di leggere la tua documentazione. È qui che puoi dire all'utente che l'API è sperimentale, dovrebbe essere utilizzata a proprio rischio e così via.

Non ho mai visto nulla di simile in altre API, poiché le funzionalità sperimentali o incomplete non hanno nulla a che fare con un'API pubblica.

Dal momento che non hai scelta, metti un avviso chiaramente visibile che la parte dell'API è soggetta a modifiche.