comment_references

Referencie apenas identificadores no escopo em comentários de documentação.

FAÇA referenciar apenas identificadores que estejam no escopo em comentários de documentação.

Se você envolve identificadores como nomes de variáveis, métodos ou tipos entre colchetes, ferramentas como sua IDE e o dart doc podem criar links para eles. Para que isso funcione, garanta que todos os identificadores envolvidos por colchetes na documentação estejam no escopo.

Por exemplo, supondo que outOfScopeId esteja fora do escopo:

RUIM:

/// Returns whether [value] is larger than [outOfScopeId].
bool isOutOfRange(int value) { ... }

BOM:

/// Returns the larger of [a] or [b].
int max_int(int a, int b) { ... }

Observe que o formato de comentário com colchetes foi pensado para permitir que comentários façam referência a declarações de forma natural, mas não permite expressões arbitrárias. Em particular, referências de código entre colchetes podem consistir em qualquer um dos seguintes:

• Um identificador simples que esteja no escopo do comentário (veja a especificação sobre o que está "no escopo" em comentários de documentação). Exemplos incluem [print] e [Future].
• Dois identificadores separados por um ponto (um "identificador prefixado"), de modo que o primeiro identificador atue como identificador de namespace, como o nome de uma propriedade ou método de classe prefixado pelo nome da classe que o contém, ou um identificador de nível superior prefixado por um prefixo de import. Exemplos incluem [Future.new] (um construtor sem nome), [Future.value] (um construtor), [Future.wait] (um método estático), [Future.then] (um método de instância) e [math.max] (dado que 'dart:async' é importado com um prefixo max).
• Um identificador prefixado seguido de um par de parênteses, usado para desambiguar construtores nomeados de membros de instância (cujos nomes podem colidir). Exemplos incluem [Future.value()].
• Três identificadores separados por pontos, de modo que o primeiro identificador seja um prefixo de import, o segundo seja um elemento de nível superior, como uma classe ou uma extension, e o terceiro seja um membro desse elemento de nível superior. Exemplos incluem [async.Future.then] (dado que 'dart:async' é importado com um prefixo async).

Limitações conhecidas

A regra de lint comment_references segue a noção de referências em comentários do analyzer do Dart, que às vezes é diferente da noção do Dartdoc. A regra pode reportar referências que o Dartdoc consegue resolver, mesmo que o analyzer não consiga. Consulte sdk#57783 para mais informações.

Para ativar a regra comment_references, adicione comment_references em linter > rules no seu arquivo analysis_options.yaml:

linter:
  rules:
    - comment_references

Se você usa a sintaxe de mapa YAML para configurar as regras de lint, adicione comment_references: true em linter > rules:

linter:
  rules:
    comment_references: true