¿Cómo documentar API experimentales o incompletas como @deprecated?

12

¿Existe un buen término que sea similar pero diferente de "desaprobar" para significar que un método o API está en la base del código pero que no debe usarse porque su implementación no está completa o probablemente cambiará? (Sí, lo sé, esos métodos no deberían ser públicos, yada yada yada. No creé mi situación, solo estoy tratando de sacar lo mejor de eso).

¿Qué sugiere la gente? Experimental, incompleto, ¿algo más?

Si estoy compilando documentación de javadoc para esta API que todavía está en flujo, ¿debería usar la etiqueta @deprecated o hay una convención mejor? Para mí, @deprecated implica que esta API es antigua y que hay disponible un mecanismo preferido más nuevo. En mi situación, no hay alternativa, pero algunos de los métodos en la API no están terminados y, por lo tanto, no deberían usarse. En este punto no puedo hacerlos privados, pero me gustaría poner advertencias claras en los documentos.

documentation terminology api documentation-generation javadocs Michael Levy
fuente
Una etiqueta "Inestable" también sería útil. El significado sería algo diferente. "Se supone que esto funciona bien, pero podríamos hacer algunos cambios en el futuro".
Borjab

Respuestas:

8

El término apropiado es probablemente incubadora , este es uno usado por Google y Apache:

  • google-web-toolkit-incubator

    La incubadora oficial de widgets y bibliotecas para Google Web Toolkit ...

  • Incubadora Apache

    ... la puerta de entrada para proyectos de código abierto destinados a convertirse en proyectos completos de Apache Software Foundation ...

Si observa más de cerca los proyectos mencionados anteriormente, puede observar que las API "experimentales" (por ejemplo, en GWT) tienden a tener nombres de paquetes "dedicados", como com.google.gwt.gen2. Esto es para evitar la contaminación futura API "finalizada" destinada al consumo público permanente, porque, ya sabes,

"Las API públicas, como los diamantes, son para siempre. Tienes una oportunidad de hacerlo bien, así que da lo mejor de ti ..." (Joshua Bloch, Cómo diseñar una buena API y por qué es importante )

mosquito
fuente
2
Me estaba inclinando hacia "Experimental" después de ver API como developer.chrome.com/extensions/experimental.html
Michael Levy
10

Lo usaría @deprecatedpor razones puramente prácticas.

Aunque @deprecatedno transmite el significado exacto que le gustaría, tiene una ventaja significativa: el compilador de Java tiene soporte incorporado. Compilar con -deprecationflag le permite encontrar todos los lugares donde anula un método obsoleto, lo que ayuda a sus usuarios a encontrar códigos sospechosos muy rápidamente. Puede usar la @deprecatedetiqueta Javadoc para explicar lo que realmente está sucediendo a cualquiera a quien le interese leer su documentación. Aquí es donde puede decirle al usuario que la API es experimental, debe usarse bajo su propio riesgo, y así sucesivamente.

dasblinkenlight
fuente
1
+1. Excelente punto Tener un soporte integrado es esencial para tales partes de la API, y alienta a los usuarios a ver la documentación para comprender por qué esas partes están marcadas como depreciadas.
Arseni Mourzenko
2
Me inclinaba hacia algo como "* @ obsoleto. Esta es una API experimental y es probable que cambie" como mínimo para obtener el IDE y los documentos para resaltar el método y luego tener una breve explicación.
Michael Levy
Solo recuerde que en desuso creará muchas advertencias. Esto podría no ser tan malo como parece. Ser advertido de las características experimentales podría estar bien.
Borjab
3

Nunca he visto algo así en otras API, ya que las características experimentales o incompletas no tienen nada que ver en una API pública.

Como no tiene opciones, simplemente coloque una advertencia claramente visible de que la parte de la API está sujeta a cambios.

Arseni Mourzenko
fuente
Bien. Por ejemplo, tenemos: junit.org/apidocs/org/junit/experimental/package-summary.html Por cierto, usar el paquete fue una idea horrible. Una vez que la API es inestable, debe cambiar el paquete para romper todas las dependencias. Una anotación en Java hubiera sido mucho mejor
Borjab