para - tutorial django

¿Existen prácticas recomendadas o mejores para seguir al renombrar funciones en una nueva versión de un paquete?

Question

Estoy actualizando un paquete viejo y acortando un montón de nombres de funciones realmente largos. ¿Cómo le informo a un usuario que la función anterior ha quedado en desuso? Documentar todo con roxygen2 así que me pregunto si #'' @alias es lo que debería usar? ¿Pensamientos?

Answer 1

Aunque solo esté acortando los nombres de las funciones, todavía lo trataría con la misma fanfarria que cualquier cambio en la API pública del paquete: con etapas de desactualización / extinción de las funciones anteriores a medida que se incorporan las nuevas funciones.

En la primera fase, para cada función que desee acortar el nombre de (vamos a llamarlo transmute_my_carefully_crafted_data_structure_into_gold ), mantiene una función con esa firma, pero mueve todo el código real a su función recién nombrada (llamémosla alchemy ).

Inicialmente:

transmute_my_carefully_crafted_data_structure_into_gold <- function(lead, alpha=NULL, beta=3) {
  # TODO: figure out how to create gold
  # look like we are doing something
  Sys.sleep(10)
  return("gold")
}

Primer lanzamiento con nuevos nombres:

transmute_my_carefully_crafted_data_structure_into_gold <- function(lead, alpha=NULL, beta=3) {
  .Deprecated("alchemy") #include a package argument, too
  alchemy(lead=lead, alpha=alpha, beta=beta)
}

alchemy <- function(lead, alpha=NULL, beta=3) {
  # TODO: figure out how to create gold
  # look like we are doing something
  Sys.sleep(10)
  return("gold")
}

Para que transmute_my_carefully_crafted_data_structure_into_gold comience como una capa delgada alrededor de .Deprecated , con una llamada adicional .Deprecated .

> transmute_my_carefully_crafted_data_structure_into_gold()
[1] "gold"
Warning message:
''transmute_my_carefully_crafted_data_structure_into_gold'' is deprecated.
Use ''alchemy'' instead.
See help("Deprecated") 
> alchemy()
[1] "gold"

Si realiza cambios en la alchemy , transmute_my_carefully_crafted_data_structure_into_gold sigue llevando a cabo, ya que simplemente llama al primero. Sin embargo, no cambia la firma de transmute_my_carefully_crafted_data_structure_into_gold incluso si alchemy hace; en ese caso, debe asignar, lo mejor posible, los argumentos anteriores en los nuevos argumentos.

En una versión posterior, puede cambiar .Deprecated a .Defunct .

> transmute_my_carefully_crafted_data_structure_into_gold()
Error: ''transmute_my_carefully_crafted_data_structure_into_gold'' is defunct.
Use ''alchemy'' instead.
See help("Defunct")

Tenga en cuenta que esto es un error y se detiene; no continúa y llama a la alchemy .

Podrías, en algún lanzamiento posterior, eliminar esta función por completo, pero la dejaría en este estado como un poste indicador.

Mencionaste usar roxygen. Cuando realice la primera transición a la obsolescencia, puede cambiar el nombre de @rdname por obsoleto, agregar una línea al principio de la descripción diciendo que está en desuso, agregar la nueva función al @seealso. Cuando cambie a desaparecer, cambie @rdname a package-difunct.

Answer 2

En el caso de convertir nombres de funciones excesivamente largos a versiones más cortas, recomendaría simplemente exportar ambos nombres como la misma función (ver el comentario de @ Brandon). Esto permitiría que el código antiguo continúe funcionando mientras ofrece a los nuevos usuarios una alternativa más conveniente.

En mi opinión, la única razón para etiquetar algo como .Deprecated (vea @GSEE) sería si planea cambiar fundamentalmente la funcionalidad o dejar de admitir alguna característica en una versión futura. Si este es el caso, puede usar .Defunct o .Deprecated .

Answer 3

Supongo que la respuesta "correcta" depende de lo que quieras. Desde mi vista:

1. El problema con el enfoque de Jeff y Brandon es que su índice enumerará los nombres de ambas funciones y no dará ninguna indicación sobre cuál es el nombre preferido. Además, sin algún tipo de llamada .Deprecated, es aún más difícil que el usuario sepa cuál es la forma preferida de llamar a la función.
2. El problema con el enfoque de Brian era que el proceso para listar más de una función como obsoleto no estaba claro para mí.

Por lo tanto, ingrese mi ejemplo a continuación. En otra ubicación, defino las "buenas" versiones de las funciones (por ejemplo, alquimia, latinSquareDigram). Aquí defino todas las viejas versiones "malas" para las que quiero producir advertencias de depreciación. Seguí el enfoque del paquete del auto y cambié todas mis llamadas de función para que la versión obsoleta se usara ... como argumento. Esto me ha ayudado a evitar un montón de declaraciones @param desordenadas. También utilicé las directivas @name y @docType para hacer que "yourPackageName-obsoleto" aparezca en el índice. Tal vez alguien tiene una mejor manera de hacer esto?

Ahora, cada una de las funciones obsoletas aún aparece en el índice, pero dice "Funciones obsoletas en el paquete yourPackageName" junto a ellas y cualquier llamada a ellas produce una advertencia de obsolescencia. Para eliminarlos del índice, se podría soltar la directiva @aliases, pero luego tendría objetos de código no documentados a nivel de usuario que, según creo, es de mala calidad.

#'' Deprecated function(s) in the yourPackageName package
#'' 
#'' These functions are provided for compatibility with older version of
#'' the yourPackageName package.  They may eventually be completely
#'' removed.
#'' @rdname yourPackageName-deprecated
#'' @name yourPackageName-deprecated
#'' @param ... Parameters to be passed to the modern version of the function
#'' @docType package
#'' @export  latinsquare.digram Conv3Dto2D Conv2Dto3D dist3D.l
#'' @aliases latinsquare.digram Conv3Dto2D Conv2Dto3D dist3D.l
#'' @section Details:
#'' /tabular{rl}{
#''   /code{latinsquare.digram} /tab now a synonym for /code{/link{latinSquareDigram}}/cr
#''   /code{Conv3Dto2D} /tab now a synonym for /code{/link{conv3Dto2D}}/cr
#''   /code{Conv2Dto3D} /tab now a synonym for /code{/link{conv2Dto3D}}/cr
#''   /code{dist3D.l} /tab now a synonym for /code{/link{dist3D}}/cr
#'' }
#''  
latinsquare.digram <- function(...) {
  .Deprecated("latinSquareDigram",package="yourPackageName")
  latinSquareDigram(...)
}
Conv3Dto2D <- function(...) {
  .Deprecated("conv3Dto2D",package="yourPackageName")
  conv3Dto2D(...)
}
Conv2Dto3D <- function(...) {
  .Deprecated("conv2Dto3D",package="yourPackageName")
  conv2Dto3D(...)
}
dist3D.l <- function(...) {
  .Deprecated("dist3D",package="yourPackageName")
  dist3D(...)
}
NULL

Answer 4

Tuve este problema por un tiempo y no pude encontrar una buena solución. Entonces encontré esto. Aún así, las respuestas anteriores son demasiado complicadas para el caso simple donde uno solo quiere: 1) agregar un alias para que el código anterior no deje de funcionar, 2) el alias debe funcionar con la documentación incorporada, y 3) debe hacerse con roxygen2.

Primero, agregue una copia de la función:

old_function_name = new_function_name

Luego, donde se define new_function_name (), agregue al roxygen2:

#'' @export new_function_name old_function_name
#'' @aliases old_function_name

Ahora la función anterior funciona porque es solo una copia de la nueva función y la documentación funciona porque configuró el alias. La versión anterior también se exporta porque está incluida en @export.