dart doc

El comando dart doc genera documentación de referencia en HTML para el código fuente de Dart.

Para agregar texto de referencia y ejemplos a la documentación generada, usa comentarios de documentación con formato Markdown. Para obtener orientación sobre cómo escribir comentarios de documentación, consulta la guía Effective Dart: Documentación.

Para generar la documentación de tu paquete, ejecuta dart doc . desde el directorio raíz del paquete. Por ejemplo, la generación de los documentos de API para un paquete my_package podría parecerse a lo siguiente:

$ cd my_package
$ dart pub get
$ dart doc .
Documenting my_package...
...
Success! Docs generated into /Users/me/projects/my_package/doc/api

Por defecto, dart doc coloca la documentación generada y los archivos de soporte en el directorio doc/api. Para cambiar el directorio de salida, especifica una ruta con la bandera --output:

$ dart doc --output=api_docs .

Si hay algún problema con la configuración de tu paquete o los comentarios de documentación, dart doc los muestra como errores o advertencias. Si solo deseas probar si hay problemas sin guardar la documentación generada, agrega la bandera --dry-run:

$ dart doc --dry-run .

Para configurar cómo genera la documentación dart doc, crea un archivo llamado dartdoc_options.yaml en el directorio raíz de tu paquete.

Para obtener más información sobre el formato del archivo y las opciones de configuración admitidas, consulta dart.dev/go/dartdoc-options-file.

Puedes ver la documentación generada con dart doc de varias maneras.

Para ver la documentación de API que generaste con dart doc o que descargaste de internet, debes cargarlos con un servidor HTTP.

Para servir los archivos, usa cualquier servidor HTTP. Considera usar el paquete:dhttpd de pub.dev.

Para usar package:dhttpd, actívalo globalmente, luego ejecútalo y especifica la ruta de tus documentos generados. Los siguientes comandos activan el paquete y luego lo ejecutan para servir los documentos de API ubicados en doc/api:

$ dart pub global activate dhttpd
$ dart pub global run dhttpd --path doc/api

Luego, para leer la documentación generada en tu navegador, abre el enlace que muestra dhttpd, generalmente http://localhost:8080.

También puedes alojar tu documentación de API generada en línea usando cualquier servicio de alojamiento que admita contenido web estático. Dos opciones comunes son Firebase hosting y GitHub pages.

El sitio pub.dev genera y aloja documentación para las bibliotecas públicas de un paquete subido.

Para ver la documentación generada de un paquete, navega a su página y abre el enlace de API reference en el cuadro de información del lado derecho de la página. For ejemplo, puedes encontrar la documentación de la API para package:http en pub.dev/documentation/http.

dart doc también se usa para generar la documentación de referencia de la API para las bibliotecas principales de Dart.

Para ver la documentación de referencia del SDK de Dart, visita el enlace api.dart.dev que corresponda al canal de lanzamiento de Dart con el que estés desarrollando:

Para identificar y resolver problemas comunes con la documentación generada con dart doc, consulta la siguiente sección de referencia.

Si las barras de búsqueda de la documentación generada no funcionan o incluyen un texto similar a "Failed to initialize search", es posible que se deba a uno de los siguientes escenarios:

1. Estás accediendo a los documentos desde tu propio sistema de archivos, pero no se están sirviendo ni cargando con un servidor HTTP. Para aprender a servir documentos de API locales, consulta cómo ver la documentación generada localmente.
2. El archivo index.json generado por dart doc falta o es inaccesible desde el directorio de documentación o desde tu servidor web alojado. Intenta regenerar los documentos y validar tu configuración de alojamiento.

Si faltan las barras laterales de la documentación generada o incluyen un texto similar a "Failed to load sidebar", es posible que se deba a uno de los siguientes escenarios:

1. Estás accediendo a los documentos desde tu propio sistema de archivos, but los documentos no se están sirviendo ni cargando con un servidor HTTP. Para aprender a servir documentos de API locales, consulta cómo ver la documentación local.
2. El comportamiento base-href de los documentos generados está configurado. Esta opción de configuración está obsoleta (deprecated) y ya no debería usarse. Intenta eliminar la opción y usar el comportamiento por defecto de dart doc. Si el comportamiento por defecto rompe los enlaces en tu documentación generada, por favor abre un reporte de problema (file an issue).

Si no puedes encontrar o acceder a la documentación generada para una API de la cual esperas tener documentación, es posible que se deba a uno de los siguientes escenarios:

1. El paquete no expone la API que estás buscando como una API pública. dart doc solo genera documentación para bibliotecas y miembros públicos que están expuestos para que otros paquetes los importen y usen. Para obtener más información sobre cómo configurar las bibliotecas públicas de un paquete, consulta la guía de diseño de paquetes sobre bibliotecas públicas.
2. La URL a la que estás intentando acceder tiene un uso incorrecto de mayúsculas/minúsculas. Por defecto, dart doc genera nombres de archivo que distinguen entre mayúsculas y minúsculas (case-sensitive), coinciden con sus declaraciones de fuente correspondientes y tienen una extensión .html. Intenta verificar si la URL coincide con estas expectativas.

Si ves texto en lugar de iconos como los botones de menú y de tema, es probable que tu navegador no haya podido cargar la fuente Material Symbols. Algunas opciones para solucionar esto incluyen:

1. Intenta usar un proxy que permita el acceso a los servidores de Google Fonts.
2. Actualiza las páginas generadas para usar una versión local de la fuente.