Come documentare API sperimentali o incomplete come @deprecated?

11

Esiste un termine valido che è simile ma diverso da "deprecate" per indicare che un metodo o un'API si trova nella base del codice ma non dovrebbe 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.)

Che cosa suggeriscono le persone? Sperimentale, incompleto, qualcos'altro?

Se sto costruendo la documentazione di javadoc per questa API che è ancora in flusso, dovrei usare il tag @deprecated o c'è una convenzione migliore? Per me @deprecated implica che questa API sia vecchia e che sia 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 mi piacerebbe mettere degli avvertimenti chiari nei documenti.

    
posta Michael Levy 15.10.2012 - 21:38
fonte

3 risposte

7

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

Se dai un'occhiata 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 le future API "finalizzate" destinate al consumo pubblico permanente - perché, come sapete,

"Public APIs, like diamonds, are forever. You have one chance to get it right so give it your best..." (Joshua Bloch, How to Design a Good API and Why it Matters)

    
risposta data 15.10.2012 - 21:52
fonte
10

Vorrei utilizzare @deprecated per motivi prettamente pratici.

Sebbene @deprecated non trasmetta il significato esatto che vorresti, ha un vantaggio significativo: il compilatore Java ha un supporto integrato per questo. La compilazione con -deprecation flag ti consente di trovare tutte le posizioni in cui sovrascrivi un metodo deprecato, aiutando gli utenti a trovare il codice sospetto molto rapidamente. Puoi usare @deprecated tag Javadoc per spiegare cosa sta realmente accadendo a chiunque tenti di leggere la tua documentazione. È qui che potresti dire all'utente che l'API è sperimentale, dovrebbe essere usato a proprio rischio e così via.

    
risposta data 15.10.2012 - 21:54
fonte
3

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

Dato che non hai scelte, metti un avvertimento chiaramente visibile che la parte dell'API è soggetta a modifiche.

    
risposta data 15.10.2012 - 21:52
fonte