es.davy.ai

Preguntas y respuestas de programación confiables

¿Tienes una pregunta?

Si tienes alguna pregunta, puedes hacerla a continuación o ingresar lo que estás buscando.

¿Cómo documentar las funcionalidades de Cargo?

20 Jul, 2023 Programación

Estoy usando Características de Cargo para la compilación condicional de algunas cosas en una biblioteca.

Mientras documentaba la biblioteca, me di cuenta de que las características de Cargo no aparecen en ninguna parte de la documentación generada. Cuando generé la documentación con cargo doc --all-features, esperaba ver algún tipo de etiqueta que indique al usuario que la estructura X solo está disponible cuando se habilita la característica Y.

Escribir esta información en cada elemento manualmente parece ser propenso a errores, ¿hay alguna manera de generar automáticamente algo así?

Tags:  , ,

Answer

  1. Avatar for davy.ai
    davy.ai

    Sí, hay una forma de generar automáticamente esa información en la documentación generada de tu biblioteca de Rust. Puedes usar el soporte incorporado de Rustdoc para documentar indicadores de características.

    En tu código, puedes anotar cada estructura, enumeración o función que dependa de una característica con el atributo #[cfg(feature = "my_feature")]. Por ejemplo:

    #[cfg(feature = "my_feature")]
pub struct X {
    // campos aquí
}

    Luego, en tu documentación, puedes usar el atributo #[cfg_attr] para especificar que cierto párrafo de texto o código de ejemplo solo debe incluirse si una determinada característica está habilitada. Por ejemplo:

    #[cfg_attr(feature = "my_feature", doc = "Disponible solo con la característica \"my_feature\".")]
pub struct X {
    // campos aquí
}

    Ahora, cuando generes la documentación con cargo doc --all-features, la documentación generada incluirá una nota para cada elemento que dependa de una característica, indicando qué característica es necesaria para que esté disponible.

    Usando este enfoque, puedes evitar errores y mantener tu documentación sincronizada con tu código, al mismo tiempo que proporcionas información útil a los usuarios de tu biblioteca.

Comments are closed.