Dartdoc: Precisa da capacidade de criar documentos de API em nível de biblioteca sem uma tag de biblioteca explícita.

dartdoc obtém o comentário doc para todos os elementos do analisador. Portanto, o analisador precisaria ser modificado para suportar a obtenção de comentários de documentos de um arquivo dart antes da primeira declaração.

@Sfshaza , você poderia abrir um problema para o analisador e vinculá-lo aqui? Obrigado!

https://github.com/dart-lang/analyzer_cli/issues/81

Após alguma discussão, a nova regra proposta é mais simples:

Use o primeiro comentário de documento anexado a qualquer diretiva (importação, exportação, etc.).

Essa correção foi feita no analisador. Atualizar para o novo pacote de analisador, atual 0.27.1 + 2, corrigirá esse problema.

Eu acho que isso está consertado?

Não sei se já foi consertado.

Não vejo nenhum comentário de biblioteca para a documentação do stagehand, a menos que eu adicione uma instrução de biblioteca ( library stagehand; ) acima das importações. Removemos a instrução library em https://github.com/dart-lang/stagehand/pull/307 (3/2016), v1.0.2, e foi quando os comentários da biblioteca desapareceram do dartdoc: 1.0 .2 documentação da biblioteca , documentação da biblioteca 1.0.1

Você está certo, ainda exigimos o demonstrativo da biblioteca - se foi corrigido em um ponto, foi antes de eu assumir.

E eu realmente não estou certo. Para minha surpresa, isso funciona nos testes internos do dartdoc. Não sei por que não funciona no seu caso, exigirá alguma investigação.

Muito estranho. Obrigado por investigar isso. Informe-me se houver algo que eu possa fazer para ajudar.

Alguma atualização aqui?

O estado AFAIK não mudou.

Acho que gostaríamos disso: https://github.com/dart-lang/language/issues/1073

@kevmoo Observe que reconhecemos e geramos documentos para a biblioteca, esse problema é uma solicitação para observar um bloco de comentário no início do arquivo sem uma tag de biblioteca e fingir que é um comentário de documentação da biblioteca.

@kevmoo Observe que reconhecemos e geramos documentos para a biblioteca, esse problema é uma solicitação para observar um bloco de comentário no início do arquivo sem uma tag de biblioteca e fingir que é um comentário de documentação da biblioteca.

Sim. Mas descobri que muitas pessoas estão bloqueadas quanto ao nome de suas bibliotecas. Se pudesse ser apenas "nu" para que tivéssemos um lugar para pendurar as coisas - seria bom.

Menos adivinhação para coisas como dartdoc e teste

@kevmoo A solução proposta em dart-lang / language # 1073 (ter uma tag de biblioteca sem nome, por exemplo, library; ) é a maneira que eu realmente prefiro que isso seja resolvido. Claro, isso significa menos trabalho para mim, mas mais sério é muito menos "piegas" e sujeito a falhas em termos de alteração acidental de comentários no cabeçalho do arquivo para quebrar um mapeamento hack. Se houver alguns dados dizendo que isso é um grande impacto, nós ou se tivermos usuários críticos bloqueados e não pudermos esperar por uma solução de idioma, faremos upgrade para P1.

Se você não incluir uma instrução de biblioteca, a biblioteca será implicitamente nomeada como o nome do arquivo, certo? Como main.dart teria um library main implícito. Então, por que uma instrução de biblioteca "em branco" não pode fazer a mesma coisa?

@ Levi-Lesches Nenhuma razão particular, além do idioma, precisa suportar uma instrução library; sem nome.

Sim, concordo totalmente - então é isso que você esperaria que uma declaração library; fizesse? O mesmo como se não estivesse lá?

Sim, concordo totalmente - então é isso que você esperaria que uma declaração library; fizesse? O mesmo como se não estivesse lá?

Do meu ponto de vista, ele elimina os hacks que temos agora para permitir anotações "flutuantes" - sem ter que pensar no nome da biblioteca.

@ Levi-Lesches Praticamente. A única diferença seria que o analisador seria capaz de conectar não apenas anotações, mas também documentação especificamente a essa instrução e, portanto, retornar LibraryElement s para consumidores de ferramentas downstream como o dartdoc.

Uma declaração library; faria exatamente a mesma coisa que nenhuma declaração de biblioteca, exceto que você poderia pendurar anotações e dartdoc nela. É uma declaração que representa a própria biblioteca, como library foo.bar.baz; , mas, ao contrário deste último, também não nomeia a biblioteca.

Uma biblioteca sem declaração de biblioteca tem o nome vazio e library; também daria o nome vazio à biblioteca.