Dartdoc: Los documentos generados para complementos de flutter también incluyen el dardo: documentos

Este es un error de dartdocs.org, pero no tengo claro exactamente qué tipo de error de dartdocs.org.

Supongo que esto probablemente tenga algo que ver con flutter enviando su propio SDK y dartdocs.org sin excluir el SDK de flutter explícitamente en la línea de comandos (o incluyéndolo incorrectamente).

La inclusión de dart:ui en los documentos generados parecería confirmar esta hipótesis.

https://www.dartdocs.org/documentation/url_launcher/0.4.1/log.txt

El registro sugiere que dartdoc no reconoce que el SDK de flutter no forma parte del paquete. Pero por qué no está tan claro.

@ jcollins-g en caso de que necesite una reproducción local, estos pasos funcionan para mí:

git clone https://github.com/flutter/plugins.git
cd plugins/packages/url_launcher/
export FLUTTER_ROOT=<path to where you have flutter>/flutter
dartdoc

¿Alguna noticia @jcollins-g?

Puedo reproducirlo y estoy trabajando en un conjunto de banderas de línea de comando para que usted las use mientras busco una solución más permanente.

@mit-mit funciona con el siguiente indicador de línea de comando:

--exclude dart.collection,dart.math,dart.core,dart.developer,dart.io,dart.ui,dart.isolate,dart.convert,dart.async,dart.typed_data

Esto será seguro de usar con y sin la solución real a este problema.

degradando a P2 ya que hay una solución, pero aún intentaré solucionar esto pronto.

Esto ya no es necesario en la cabeza; El cálculo del SDK ahora es lo suficientemente inteligente como para no intentar incluir los componentes del SDK en los complementos de flutter.

@jcollins-g ¿Esto soluciona $ dartdoc tratando de analizar un montón de archivos, no relacionados con mi aplicación flutter?

salida.txt

@ jcollins-g Esa solución no funciona para mí. ¡Todavía está analizando un montón de archivos que están fuera del directorio lib/ de mi proyecto!

Hola @devxpy ,

dartdoc analiza todos los archivos en todos los paquetes accesibles a través del árbol de importación y exportación de su proyecto (este problema fue que a veces pensamos que necesitábamos documentar algunos de ellos cuando eso no era apropiado) y este es el comportamiento esperado. Necesita hacer esto debido a la forma en que funcionan las macros de dartdoc y el alcance de referencia de comentarios, aunque probablemente podría optimizarse para hacer esto solo a pedido.

Sin embargo, si está generando documentos para cosas que no deberían serlo, sería apropiado abrir este u otro error.

aunque probablemente podría optimizarse para hacer esto solo bajo demanda.

¿El mecanismo actual no almacena cosas en caché?
Porque actualmente analiza todo de nuevo, lo que lleva una cantidad de tiempo absurdamente larga, para una aplicación relativamente pequeña.

@devxpy

Lamentablemente, no, no se almacena en caché y, de hecho, lleva una cantidad de tiempo absurdamente larga. He tenido algunas ideas sobre cómo mejorar eso, pero el rendimiento de dartdoc no ha sido una prioridad lo suficientemente alta como para poder asignar el tiempo.

@devxpy Para ampliar muy brevemente, el almacenamiento en caché no es sencillo para dartdoc, ya que un cambio en archivos aparentemente no relacionados puede afectar la documentación generada para otro archivo. Esto se debe a las macros de alcance global y algunas referencias de comentarios que pueden tener, así como a la canonicalización de la interfaz pública de dartdoc. Un diseño para solucionar esto tendrá algunas heurísticas para eliminar esos problemas en casos comunes, o podemos cambiar algunas de nuestras reglas de alcance y luego adoptar la estrategia del servidor de análisis de invalidaciones específicas cuando se detectan cambios. No es una cantidad trivial de trabajo en cualquier caso (aunque ciertamente no es imposible)

¡Gracias por la explicación detallada!

@ jcollins-g ¿Un compilador de "recarga en caliente" basado en un observador de archivos requeriría una cantidad similar de esfuerzo?

@devxpy De hecho, diría que aún más esfuerzo. Hay un equipo de gente que está haciendo algo así en https://github.com/dart-lang/build y, por supuesto, Flutter tiene soporte de recarga en caliente.