dart doc

O comando dart doc gera documentação de referência em HTML para código-fonte Dart.

Para adicionar texto de referência e exemplos à documentação gerada, use comentários de documentação com formatação Markdown. Para orientação sobre como escrever comentários de documentação, consulte o guia Effective Dart: Documentation.

Para gerar a documentação do seu pacote, execute dart doc . a partir do diretório raiz do pacote. Por exemplo, gerar os documentos de API de um pacote my_package pode ser parecido com o seguinte:

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

Por padrão, dart doc coloca a documentação gerada e os arquivos de suporte no diretório doc/api. Para alterar o diretório de saída, especifique um caminho com a flag --output:

$ dart doc --output=api_docs .

Se houver algum problema na configuração do pacote ou nos comentários de documentação, o dart doc os reporta como erros ou avisos. Se você quiser apenas testar a existência de problemas sem salvar a documentação gerada, adicione a flag --dry-run:

$ dart doc --dry-run .

Para configurar como o dart doc gera a documentação, crie um arquivo chamado dartdoc_options.yaml no diretório raiz do seu pacote.

Para saber mais sobre o formato do arquivo e as opções de configuração suportadas, consulte dart.dev/go/dartdoc-options-file.

Você pode visualizar a documentação gerada com dart doc de várias maneiras.

Para visualizar os documentos de API que você gerou com dart doc ou baixou da internet, você precisa carregá-los com um servidor HTTP.

Para servir os arquivos, use qualquer servidor HTTP. Considere usar o package:dhttpd do pub.dev.

Para servir a documentação gerada, execute o package:dhttpd diretamente do pub.dev e especifique o caminho da documentação gerada. O comando a seguir serve os documentos de API localizados em doc/api:

$ dart run dhttpd@ --path doc/api

Para ler a documentação gerada no navegador, abra o link que o dhttpd exibe, geralmente http://localhost:8080.

Você também pode hospedar online os documentos de API gerados, usando qualquer serviço de hospedagem que suporte conteúdo web estático. Duas opções comuns são o Firebase hosting e o GitHub pages.

O site pub.dev gera e hospeda a documentação das bibliotecas públicas de um pacote publicado.

Para visualizar a documentação gerada de um pacote, acesse a página dele e abra o link API reference na caixa de informações do lado direito da página. Por exemplo, você pode encontrar os documentos de API do package:http em pub.dev/documentation/http.

O dart doc também é usado para gerar a documentação de referência da API das bibliotecas principais do Dart.

Para visualizar a documentação de referência do Dart SDK, acesse o link do api.dart.dev correspondente ao canal de lançamento do Dart que você está usando:

Para identificar e resolver problemas comuns com a documentação gerada pelo dart doc, consulte a seção de referência a seguir.

Se as barras de pesquisa da documentação gerada não funcionarem ou exibirem um texto semelhante a "Failed to initialize search", é possível que ocorra um dos seguintes cenários:

1. Você está acessando a documentação a partir do seu sistema de arquivos, mas ela não está sendo servida e carregada por um servidor HTTP. Para aprender a servir a documentação de API localmente, consulte como visualizar a documentação gerada localmente.
2. O arquivo index.json gerado pelo dart doc está ausente ou inacessível no diretório da documentação ou no seu servidor web de hospedagem. Tente gerar a documentação novamente e validar a configuração da hospedagem.

Se as barras laterais da documentação gerada estiverem ausentes ou exibirem um texto semelhante a "Failed to load sidebar", é possível que ocorra um dos seguintes cenários:

1. Você está acessando a documentação a partir do seu sistema de arquivos, mas ela não está sendo servida e carregada por um servidor HTTP. Para aprender a servir a documentação de API localmente, consulte como visualizar a documentação local.
2. O comportamento de base-href da documentação gerada está configurado. Essa opção de configuração está obsoleta e não deve mais ser usada. Tente remover a opção e usar o comportamento padrão do dart doc. Se o comportamento padrão quebrar os links da sua documentação gerada, por favor, abra uma issue.

Se você não conseguir encontrar ou acessar a documentação gerada de uma API que deveria ter documentos, é possível que ocorra um dos seguintes cenários:

1. O pacote não expõe a API que você procura como uma API pública. O dart doc gera documentação apenas para bibliotecas e membros públicos que são expostos para que outros pacotes possam importá-los e usá-los. Para saber mais sobre a configuração das bibliotecas públicas de um pacote, consulte o guia de layout de pacotes sobre bibliotecas públicas.
2. A URL que você está tentando acessar tem letras maiúsculas e minúsculas incorretas. Por padrão, o dart doc gera nomes de arquivo que diferenciam maiúsculas de minúsculas, correspondem às declarações de origem e têm a extensão .html. Verifique se a URL corresponde a essas regras.

Se você vir texto em vez de ícones, como os botões de menu e de tema, é provável que o seu navegador não tenha conseguido carregar a fonte Material Symbols. Algumas opções para resolver isso incluem:

1. Tentar usar um proxy que permita o acesso aos servidores do Google Fonts.
2. Atualizar as páginas geradas para usar uma versão local da fonte.