Dartdoc: `` `desencadeia algum tipo de destaque de sintaxe

Antes de consertar, precisaremos verificar quantos blocos existem em pacotes importantes que podem estar dependendo disso e migrá-los se necessário.

Eu acho que _a maioria_ dos casos de `` `em dart docs não são especificados com um idioma, caso em que o destaque.js escolhe um com sua" detecção automática de idioma. " Eu diria que a maioria desses casos são exemplos de código Dart, e não tenho certeza do que o destaque.js "detecta" nesses casos, haha.

Isso é provavelmente semelhante ao tratamento do GitHub de crases não específicos de linguagem: https://docs.github.com/en/github/writing-on-github/creating-and-highlighting-code-blocks

Uma maneira alternativa de resolver isso seria permitir que blocos pré-formatados especifiquem texto simples.

Sim, atualmente verificamos se nada foi especificado e adicionamos Dart .

Poderíamos acrescentar manipulação para um costume ```plain opção, em seguida, definir a classe para plaintext ou nohighlight vez .

_Realmente, minha verdadeira esperança é terminar meu marcador de sintaxe escrito em Dart para que possamos executar o destaque durante a renderização ao invés do cliente e controlar tudo ..._

Eu ficaria bem com dartdocs falhando se ele se deparasse com um bloco `` `sem idioma especificado. Os padrões são perigosos e, aqui, ser explícito é sempre melhor para quem está lendo a documentação.

Ah, eu perdi que adicionamos essa classe no renderizador. Aceito uma falha, contanto que raramente seja encontrada o suficiente para ser fácil de lidar na migração, caso contrário, teremos que ter algum tipo de plano de migração.

dartdoc agora avisa sobre blocos protegidos de código sem linguagem, a partir de https://github.com/dart-lang/dartdoc/pull/2559.

Isso é uma mudança de comportamento ou codificação de um comportamento existente?

Tive a impressão de que o DartDoc sempre usou a sintaxe do Dart, quer você tenha escrito dart ou não. Isso foi verdade em algum ponto?
Talvez apenas para código indentado, em vez de código entre chaves?

(Existe uma documentação oficial do formato DartDoc e o que isso significa? Especialmente os links de código não são definidos apenas por markdown).

Isso é uma _mudança_ de comportamento ou codificação de um comportamento existente?

Tive a impressão de que o DartDoc sempre usou a sintaxe do Dart, quer você tenha escrito dart ou não. Isso foi verdade em algum ponto?
Talvez apenas para código indentado, em vez de código entre chaves?

Um pouco de cada. O Dartdoc usa a sintaxe do DART por padrão em blocos de código, mas isso causou problemas nos casos em que o usuário realmente pretende que haja texto simples (daí o bug). As alterações de aviso têm o objetivo de encorajar a explicitação e o suporte a texto simples será adicionado para que quando os usuários desejarem, ele estará disponível.

(Existe uma documentação oficial do formato DartDoc e o que isso significa? Especialmente os links de código não são definidos apenas por markdown).

Infelizmente, a especificação não acompanhou a implementação. Eu escrevi o início de uma sintaxe para links de código como parte de um redesenho para oferecer suporte total aos métodos de extensão, aqui: https://docs.google.com/document/d/11Vzx7PjSNo55YpVEx1BBUlEUPkl6CUpHZ4gFcefBE1I/edit?resourcekey=0-xUb52CNfZw8SC8SC8SC8SC8SC8.

Fora das breves notas aqui, não há especificação formal para este ou outros elementos do comportamento do dartdoc. Indiscutivelmente, deveria haver. A documentação existe de forma mais geral no README. @parlough , provavelmente devemos atualizar o README / outros documentos para incluir mais detalhes sobre os blocos de código, incluindo suas alterações.

Posso dar uma olhada na adição de mais documentação aqui e talvez no site-www também em torno de blocos de código. Assim que eu chegar a ele, farei uma cópia de todas as alterações.