Arquivos de dicas

Um arquivo de dica contém macros que, de outra forma, fariam com que regiões de código fossem ignoradas pelo analisador de banco de dados de navegação em C++. Quando você abre um projeto Visual Studio C++, o analisador analisa o código em cada arquivo de origem no projeto e cria um banco de dados com informações sobre cada identificador. O IDE usa essas informações para oferecer suporte a recursos de navegação de código, como o navegador Class View e a Barra de Navegação.

O analisador de banco de dados de navegação C++ é um analisador difuso que pode analisar grandes quantidades de código em um curto período de tempo. Uma razão pela qual é rápido é porque ignora o conteúdo dos blocos. Por exemplo, ele apenas registra a localização e os parâmetros de uma função e ignora seu conteúdo. Certas macros podem causar problemas para a heurística usada para determinar o início e o fim de um bloco. Esses problemas fazem com que regiões de código sejam registradas incorretamente.

Essas regiões ignoradas podem se manifestar de várias maneiras:

• Tipos e funções ausentes no Modo de Exibiçãode Classe, Ir Para e Barra de Navegação

• Escopos incorretos na barra de navegação

• Sugestões para criar declaração/definição para funções já definidas

Um arquivo de dicas contém dicas personalizáveis pelo usuário, que têm a mesma sintaxe que as definições de macro C/C++. Visual C++ inclui um arquivo de dica interno que é suficiente para a maioria dos projetos. No entanto, você pode criar seus próprios arquivos de dicas para melhorar o analisador especificamente para seu projeto.

Importante

Se você modificar ou adicionar um arquivo de dica, precisará executar etapas adicionais para que as alterações entrem em vigor:

• Em versões anteriores ao Visual Studio 2017 versão 15.6: exclua o arquivo .sdf e/ou o arquivo VC.db na solução para todas as alterações.
• No Visual Studio 2017 versão 15.6 e posterior: feche e reabra a solução depois de adicionar novos arquivos de dica.

Cenário

#define NOEXCEPT noexcept
void Function() NOEXCEPT
{
}

Sem um arquivo de dica, Function não aparece no Modo de Exibição de Classe, Ir Para ou na Barra de Navegação. Depois de adicionar um arquivo de dica com essa definição de macro, o analisador agora entende e substitui a macro, o NOEXCEPT que permite analisar corretamente a função:

#define NOEXCEPT

Macros disruptivas

Há duas categorias de macros que interrompem o analisador:

• Macros que encapsulam palavras-chave que adornam uma função

  #define NOEXCEPT noexcept
  #define STDMETHODCALLTYPE __stdcall
  

  Para esses tipos de macros, somente o nome da macro é necessário no arquivo de dica:

  #define NOEXCEPT
  #define STDMETHODCALLTYPE
  

• Macros que contêm colchetes desequilibrados

  #define BEGIN {
  

  Para esses tipos de macros, o nome da macro e seu conteúdo são necessários no arquivo de dica:

  #define BEGIN {
  

Suporte ao Editor

A partir do Visual Studio 2017 versão 15.8, há vários recursos para identificar macros com interrupções:

• As macros que estão dentro de regiões ignoradas pelo analisador são realçadas.

• Há uma Ação Rápida para criar um arquivo de dica que inclua a macro realçada ou, se houver um arquivo de dica existente, para adicionar a macro ao arquivo de dica.

Depois de executar qualquer uma das Ações Rápidas, o analisador repara os arquivos afetados pelo arquivo de dica.

Por padrão, a macro de problema é realçada como uma sugestão. O destaque pode ser alterado para algo mais percetível, como um rabisco vermelho ou verde. Use a opção Macros em regiões de navegação ignoradas na seção Rabiscos de código emOpções> de ferramentas>Editor> de textoC/C++>View.

Exibir erros de banco de dados de navegação

O comando de menuErros do Banco de Dados de Navegação de Exibição do Projeto> exibe todas as regiões que não conseguiram analisar na Lista de Erros. O comando destina-se a simplificar a criação do arquivo de dica inicial. No entanto, o analisador não pode dizer se a causa do erro foi uma macro perturbadora, então você deve avaliar cada erro. Execute o comando Exibir erros do banco de dados de navegação e navegue até cada erro para carregar o arquivo afetado no editor. Depois que o arquivo é carregado, se alguma macro estiver dentro da região, ela será realçada. Você pode invocar as Ações Rápidas para adicioná-las a um arquivo de dicas. Após uma atualização do arquivo de dicas, a lista de erros é atualizada automaticamente. Como alternativa, se você estiver modificando o arquivo de dica manualmente, poderá usar o comando Rescan Solution para disparar uma atualização.

Arquitetura

Os arquivos de dica estão relacionados a diretórios físicos, não aos diretórios lógicos mostrados no Gerenciador de Soluções. Não é necessário adicionar um arquivo de dicas ao seu projeto para que o arquivo de dicas tenha um efeito. O sistema de análise usa arquivos de dica somente quando analisa arquivos de origem.

Cada arquivo de dica é chamado cpp.hint. Muitos diretórios podem conter um arquivo de dica, mas apenas um arquivo de dica pode ocorrer em um diretório específico.

Seu projeto pode ser afetado por zero ou mais arquivos de dica. Se não houver arquivos de dica, o sistema de análise usa técnicas de recuperação de erros para ignorar o código-fonte indecifrável. Caso contrário, o sistema de análise usa a seguinte estratégia para encontrar e coletar dicas.

Ordem de pesquisa

O sistema de análise procura arquivos de dica nos diretórios na seguinte ordem.

• O diretório que contém o pacote de instalação para Visual C++ (vcpackages). Este diretório contém um arquivo de dica interno que descreve símbolos em arquivos de sistema usados com freqüência, como windows.h. Consequentemente, seu projeto herda automaticamente a maioria das dicas de que precisa.

• O caminho do diretório raiz de um arquivo de origem para o diretório que contém o próprio arquivo de origem. Em um projeto típico do Visual Studio C++, o diretório raiz contém a solução ou o arquivo de projeto.

  A exceção a essa regra é se um arquivo stop estiver no caminho para o arquivo de origem. Um arquivo stop é qualquer arquivo chamado cpp.stop. Um arquivo de parada fornece controle adicional sobre a ordem de pesquisa. Em vez de iniciar a partir do diretório raiz, o sistema de análise pesquisa do diretório que contém o arquivo stop para o diretório que contém o arquivo de origem. Em um projeto típico, você não precisa de um arquivo stop.

Recolha de Sugestões

Um arquivo de dicas contém zero ou mais dicas. Uma dica é definida ou excluída como uma macro C/C++. Ou seja, a #define diretiva de pré-processador cria ou redefine uma dica e a #undef diretiva exclui uma dica.

O sistema de análise abre cada arquivo de dica na ordem de pesquisa descrita anteriormente. Ele acumula as dicas de cada arquivo em um conjunto de dicas efetivas e, em seguida, usa as dicas efetivas para interpretar os identificadores em seu código.

O sistema de análise usa estas regras para acumular dicas:

• Se a nova dica especificar um nome que ainda não está definido, a nova dica adicionará o nome às dicas efetivas.

• Se a nova dica especificar um nome que já está definido, a nova dica redefinirá a dica existente.

• Se a nova dica for uma #undef diretiva que especifica uma dica efetiva existente, a nova dica excluirá a dica existente.

A primeira regra significa que as dicas eficazes são herdadas de arquivos de dicas abertos anteriormente. As duas últimas regras significam que as dicas posteriores na ordem de pesquisa podem substituir as dicas anteriores. Por exemplo, você pode substituir quaisquer dicas anteriores se criar um arquivo de dica no diretório que contém um arquivo de origem.

Para obter uma descrição de como as dicas são coletadas, consulte a seção Exemplo .

Sintaxe

Você cria e exclui dicas usando a mesma sintaxe das diretivas de pré-processador para criar e excluir macros. Na verdade, o sistema de análise usa o pré-processador C/C++ para avaliar as dicas. Para obter mais informações sobre as diretivas de pré-processador, consulte Diretiva #define (C/C++) e Diretiva #undef (C/C++).

Os únicos elementos de sintaxe incomuns são as @<cadeias de caracteres , @=, e @> de substituição. Essas cadeias de caracteres de substituição específicas do arquivo de dicas são usadas apenas em macros de mapa . Um mapa é um conjunto de macros que relacionam dados, funções ou eventos a outros dados, funções ou manipuladores de eventos. Por exemplo, MFC usa mapas para criar mapas de mensagens e ATL usa mapas para criar mapas de objetos. As cadeias de caracteres de substituição específicas do arquivo de dicas marcam os elementos iniciais, intermediários e finais de um mapa. Apenas o nome de uma macro de mapa é significativo. Portanto, cada cadeia de caracteres de substituição oculta intencionalmente a implementação da macro.

As dicas usam esta sintaxe:

Sintaxe	Significado
#define dica-nomesubstituição-string #define nome-dica(parâmetro, ...)corda de substituição	Uma diretiva de pré-processador que define uma nova dica ou redefine uma dica existente. Após a diretiva, o pré-processador substitui cada ocorrência de hint-name no código-fonte por replacement-string. A segunda forma de sintaxe define uma dica semelhante a uma função. Se uma dica semelhante a uma função ocorrer no código-fonte, o pré-processador primeiro substituirá cada ocorrência de parâmetro na cadeia de caracteres de substituição pelo argumento correspondente no código-fonte e, em seguida, substituirá hint-name por replacement-string.
@<	Uma cadeia de caracteres de substituição específica do arquivo de dicas que indica o início de um conjunto de elementos de mapa.
@=	Uma cadeia de caracteres de substituição específica do arquivo de dica que indica um elemento de mapa intermediário. Um mapa pode ter vários elementos de mapa.
@>	Uma cadeia de caracteres de substituição específica do arquivo de dica que indica o final de um conjunto de elementos de mapa.
#undef nome-dica	A diretiva de pré-processador que exclui uma dica existente. O nome da dica é fornecido pelo identificador hint-name .
// comentário	Um comentário de linha única.
/* comentar*/	Um comentário de várias linhas.

Exemplo

Este exemplo mostra como as dicas são acumuladas de arquivos de dicas. Os arquivos Stop não são usados neste exemplo.

A ilustração mostra alguns dos diretórios físicos em um projeto Visual Studio C++. Há arquivos de dicas nos vcpackagesdiretórios , Debug, A1e A2 .

Diretórios de arquivos de dicas

Diretórios e conteúdo do arquivo de dicas

Esta lista mostra os diretórios neste projeto que contêm arquivos de dica e o conteúdo desses arquivos de dica. Apenas algumas das muitas dicas no arquivo de dicas de vcpackages diretório estão listadas:

• vcpackages

  // vcpackages (partial list)
  #define _In_
  #define _In_opt_
  #define _In_z_
  #define _In_opt_z_
  #define _In_count_(size)
  

• Depurar

  // Debug
  #undef _In_
  #define OBRACE {
  #define CBRACE }
  #define RAISE_EXCEPTION(x) throw (x)
  #define START_NAMESPACE namespace MyProject {
  #define END_NAMESPACE }
  

• A1

  // A1
  #define START_NAMESPACE namespace A1Namespace {
  

• A2

  // A2
  #undef OBRACE
  #undef CBRACE
  

Dicas eficazes

Esta tabela lista as dicas efetivas para os arquivos de origem neste projeto:

• Arquivo de origem: A1_A2_B.cpp

• Dicas eficazes:

  // vcpackages (partial list)
  #define _In_opt_
  #define _In_z_
  #define _In_opt_z_
  #define _In_count_(size)
  // Debug...
  #define RAISE_EXCEPTION(x) throw (x)
  // A1
  #define START_NAMESPACE namespace A1Namespace {
  // ...Debug
  #define END_NAMESPACE }
  

Estas notas aplicam-se à lista anterior:

• As dicas efetivas são dos vcpackagesdiretórios , Debug, A1, e A2 .

• A diretiva #undef no arquivo de dica Debug removeu a dica #define _In_ no arquivo de dica de vcpackages diretório.

• O arquivo de dica no diretório redefine START_NAMESPACEo A1 .

• A #undef dica A2 no diretório removeu as dicas para OBRACE e CBRACE no arquivo de dica do Debug diretório.

Ver também

Tipos de arquivo criados para projetos do Visual Studio C++
Diretiva #define (C/C++)
Diretiva #undef (C/C++)
Anotações SAL