Comentários no Dart

A linguagem Dart suporta 3 tipos de comentários no total: comentários de linha única, comentários multilinha e comentários de documentação; o compilador ignora o texto normal dentro dos comentários, apenas os comentários de documentação podem ser usados para gerar a documentação do código.

O objetivo dos comentários é facilitar que desenvolvedores consultem o código e entendam suas funções e propósitos. Além disso, os comentários permitem ocultar temporariamente trechos de código para depurar o programa e localizar problemas.

Com os comentários de documentação, você pode usar ferramentas para gerar uma documentação de ajuda do código automaticamente. Isso facilita a consulta das funcionalidades do seu código por você mesmo e por outros desenvolvedores.

Se você já estudou outras linguagens, conseguirá entender comentários rapidamente. A sintaxe é quase igual às linguagens baseadas em C, como C, C++, Java e C#.

1. Comentário de linha única //

1. Inicia com o símbolo //;
2. Todo o conteúdo de // até o fim da linha é ignorado pelo compilador Dart;
3. Só funciona na linha atual, não suporta várias linhas.

Exemplo

void main() {
  // TODO: Refatorar para fábrica abstrata de saudação de lhamas
  print('Bem-vindo à minha fazenda de lhamas!');
}
Code language: JavaScript (javascript)

2. Comentário multilinha /* */

1. Marca de início /*, marca de fim */;
2. Todo conteúdo entre /* e */ é ignorado pelo compilador (exceto comentários de documentação, veja abaixo);
3. Suporta aninhamento.

Exemplo

void main() {
  /*
   * Criar lhamas dá muito trabalho, vale a pena considerar criar galinhas.

  Llama larry = Llama();
  larry.feed();
  larry.exercise();
  larry.clean();
   */
}Code language: Dart (dart)

No código acima, todo o conteúdo dentro das chaves está comentado, não será compilado e o compilador ignora essa parte completamente.

3. Comentários de documentação

Servem para gerar a documentação oficial de API. Quando outros desenvolvedores usarem sua biblioteca, eles conseguem consultar instruções de uso de classes, interfaces de funções, parâmetros e outros elementos, como um manual de instruções.

1. Dois formatos de escrita

• Comentário de documentação de linha única: várias linhas consecutivas com ///, tem o mesmo efeito do multilinha. Atenção: são três barras.
• Comentário de documentação multilinha: inicia com /** e termina com */. Repare no asterisco extra no início.

2. Regras sintáticas principais

1. Texto normal dentro de comentários de documentação é ignorado pelo analisador de código;
2. Sintaxe especial: identificador entre colchetes [] para referenciar classes, métodos, campos, variáveis globais, funções e parâmetros;
3. Nomes dentro dos colchetes são resolvidos no escopo léxico do código comentado;
4. Após gerar a documentação, [identificador] vira automaticamente um hiperlink para a documentação correspondente.

Exemplo

// Comentário simples de linha única: definição da classe de ração
class Food {
  String type;
  // Comentário de linha única: quantidade de fardos de ração
  int baleCount;

  Food(this.type, this.baleCount);
}

/*
Comentário multilinha comum:
Enumeração de tipos de atividade para o método de exercício da lhama
Demonstração de comentário aninhado
/* Comentário interno aninhado */
*/
enum Activity {
  walk,
  run,
  graze
}

/// Mamífero camelídeo domesticado da América do Sul (lhama, nome científico Lama glama)
///
/// Antes da colonização europeia, as civilizações andinas usavam lhamas para carne e transporte.
///
/// Assim como outros animais, lhamas precisam se alimentar: use ração do tipo [Food] e chame o método [feed].
class Llama {
  String? name;

  /// Alimenta a lhama com a ração [food] informada
  ///
  /// Uma lhama consome geralmente um fardo de feno por semana.
  void feed(Food food) {
    // Comentário de linha única: exibir mensagem de alimentação
    print("${name} comeu ${food.baleCount} fardos de ${food.type}");
  }

  /// Faz a lhama realizar a atividade [activity] por [timeLimit] minutos
  void exercise(Activity activity, int timeLimit) {
    print("${name} praticou ${activity.name} por ${timeLimit} minutos");
  }
}

void main() {
  // TODO: Ampliar para gerenciar várias lhamas futuramente
  Llama larry = Llama();
  larry.name = "Larry";

  // Criar ração de feno
  Food hay = Food("feno", 1);
  larry.feed(hay);

  // Lhama caminha por 20 minutos
  larry.exercise(Activity.walk, 20);
}
Code language: PHP (php)

Depois de gerar a documentação: [feed] aponta para a documentação do método feed da classe atual, [Food] aponta para a documentação da classe Food.

D:\dartdemo\firstdart>dart run
Building package executable...
Built firstdart:firstdart.
Larry comeu 1 fardos de feno
Larry praticou walk por 20 minutos

D:\dartdemo\firstdart>dart doc
Documenting firstdart...
Discovering libraries...
Linking elements...
Precaching local docs for 136851 elements...
Initialized dartdoc with 50 libraries
Generating docs for library firstdart.dart from package:firstdart/firstdart.dart...
Found 0 warnings and 0 errors.
Documented 1 public library in 10.3 seconds
Success! Docs generated into d:\dartdemo\firstdart\doc\apiCode language: JavaScript (javascript)

Uma pasta doc será criada na pasta do projeto, ao abri-la você verá a documentação gerada

Ferramentas complementares

1. Ferramenta geradora de documentação: dart doc Função: analisa o código fonte Dart e cria automaticamente documentação de API em HTML. A documentação oficial do Dart é feita com essa ferramenta.
2. Referência de padrões de comentários: Guia oficial «Effective Dart: Documentation», com estruturas e estilos padronizados para escrever comentários.

Resumo

Tabela comparativa

Tipo de comentário	Símbolo inicial	Multilinha	Aninhável	Finalidade
Comentário linha única	//	Não, apenas uma linha	Não	Anotações temporárias, tarefas TODO no código
Comentário multilinha comum	/* */	Sim, várias linhas	Sim	Comentar blocos grandes de código, descrições longas
Comentário de documentação	/// / /** */	Sim	Não recomendado	Escrever API de classes/métodos/variáveis, gerar documentação oficial, links para identificadores via []