Arquivos de dica

A arquivo de dicas Ajuda do Visual Studio ambiente de desenvolvimento integrado (IDE) interpretar identificadores de Visual C++, como os nomes das funções e macros.Quando você abre um projeto de Visual C++, o IDE sistema de análise analisa o código em cada arquivo de origem no projeto e reúne informações sobre todos os identificadores.Em seguida, o IDE usa essas informações para oferecer suporte a recursos como o Modo de exibição de classe navegador e o Barra de navegação.

O sistema de análise, que é apresentado em Visual C++ 2010, entenda a sintaxe de C/C++, mas poderá interpretar incorretamente uma instrução que contenha uma macro.A instrução pode ser mal interpretada se a macro faz com que o código-fonte ser sintaticamente incorreto como escrita.A instrução pode se tornar sintaticamente correta quando o código-fonte é compilado e o preprocesser substitui o Identificador de macro com sua definição. O sistema de análise funciona sem a necessidade de compilar o projeto porque ele usa arquivos de dica para interpretar macros. Portanto, um recurso de localização como Modo de exibição de classe fica imediatamente disponível.

Um arquivo de dica contém personalizável pelo usuário Dicas, que têm a mesma sintaxe como definições de macro do C/C++.Visual C++ inclui um arquivo de dica interna é suficiente para a maioria dos projetos, mas você pode criar seus próprios arquivos de dica para melhorar a maneira como o Visual Studio trata identificadores.

Cenário

Suponha que o código a seguir está em um arquivo de origem que você examine com o Modo de exibição de classe navegador.O STDMETHOD macro declara um método chamado myMethod que aceita um parâmetro e retorna um ponteiro para um HRESULT.

// Source code file.
STDMETHOD(myMethod)(int parameter1);

As definições de macro a seguir estão em um arquivo de cabeçalho separado.

// Header file.
#define STDMETHOD(method) HRESULT (STDMETHODCALLTYPE * method)
#define STDMETHODCALLTYPE __stdcall
#define HRESULT void*

O sistema de análise não pode interpretar o código-fonte, porque uma função chamada STDMETHOD parece ser declarado, e essa declaração é sintaticamente incorreta, pois ele tem duas listas de parâmetros.O sistema de análise não abrir o arquivo de cabeçalho para descobrir as definições para o STDMETHOD, STDMETHODCALLTYPE, e HRESULT macros.Como o sistema de análise não pode interpretar o STDMETHOD macro, ela ignora a declaração inteira e, em seguida, continua a análise.

O sistema de análise não usa arquivos de cabeçalho porque seu projeto pode depender de um ou mais arquivos de cabeçalho importante.Se qualquer arquivo de cabeçalho for alterado, o sistema de análise pode ter a reexaminar todos os arquivos de cabeçalho em seu projeto, o que diminui o desempenho do IDE.Em vez disso, o sistema de análise utiliza dicas que especificam como lidar com o STDMETHOD, STDMETHODCALLTYPE, e HRESULT macros.

Como você sabe que precisa de uma dica?E se você precisar de uma dica, que tipo você deve criar?É um sinal de que uma dica é necessária se o modo de exibição de um identificador na Modo de exibição de classe é inconsistente com o modo de exibição de Editor.Por exemplo, Modo de exibição de classe pode não exibir um membro da classe que você sabe que existe, ou o nome do membro está incorreto.Para obter mais informações sobre os tipos de dicas que solucionam os problemas comuns, consulte o que Macros exigem A dica? seção mais adiante neste tópico.

Arquitetura

Dica arquivos pertencem aos diretórios físicos, não os diretórios lógicos descrita na Solution Explorer.Não é necessário adicionar um arquivo de dicas ao seu projeto para o arquivo de dicas ter efeito.O sistema de análise usa arquivos de dica somente quando ele analisa arquivos de origem.

Cada arquivo de dica é chamado. cpp.hint.Portanto, muitos diretórios podem conter um arquivo de dica mas arquivo apenas uma 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 nenhum arquivo de dica, o sistema de análise utiliza técnicas de recuperação de erro para ignorar o código-fonte indecifráveis.Caso contrário, o sistema de análise utiliza a seguinte estratégia para encontrar e reunir dicas.

Ordem de pesquisa

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

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

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

  A exceção a essa regra é se um arquivo de parada é o caminho para o arquivo de origem.Um arquivo de parada oferece mais controle sobre a ordem de pesquisa e é qualquer arquivo que é chamado. cpp.Stop.Em vez de a partir do diretório raiz, o sistema de análise procura no diretório que contém os arquivos para o diretório que contém o arquivo de origem.Em um projeto típico, é necessário um arquivo de parada.

Coleta de dica

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

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

O sistema de análise utiliza as seguintes regras para acumular as dicas.

• Se a nova dica especifica um nome que já não está definido, a nova dica adiciona o nome para as dicas eficazes.

• Se a nova dica especifica um nome que já está definido, a nova dica redefine a dica existente.

• Se a nova dica é um #undef diretiva que especifica uma dica eficaz existente, a nova dica exclui a dica existente.

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

Para uma descrição de como as dicas são reunidas, consulte o Exemplo seção mais adiante neste tópico.

Sintaxe

As dicas são criadas e excluídas com a mesma sintaxe que as diretivas de pré-processador que criar e excluir macros.Na verdade, o sistema de análise utiliza o pré-processador de 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++).

São os elementos de sintaxe incomum apenas o @<, @=, e @> cadeias de caracteres de substituição.Estas são seqüências de caracteres de substituição específico de arquivo de dicas que são usadas apenas com mapa macros.Um mapa é um conjunto de macros que estão relacionados a eventos, funções ou dados a outros dados, funções ou manipuladores de eventos.Por exemplo, MFC usa mapas para criar mapas de mensagem, e ATL usa mapas para criar mapas de objeto.As seqüências de caracteres de substituição específico de arquivo de dicas indicam os elementos inicial, intermediários e final de um mapa.Somente o nome de uma macro de mapa é significativo.Portanto, cada seqüência de caracteres de substituição intencionalmente oculta a implementação da macro.

Dicas de usam a sintaxe a seguir.

Sintaxe	Significado
#definenome da dicaseqüência de caracteres de substituição #definenome da dica(parâmetro, ...)seqüência de caracteres de substituição	Uma diretiva de preprocesser que define uma nova dica ou redefine uma dica existente.Após a diretiva do pré-processador substitui cada ocorrência de nome da dica no código-fonte com seqüência de caracteres de substituição. O segundo formulário sintaxe define uma dica de função.Se ocorrer uma dica de função no código-fonte, o pré-processador primeiro substitui cada ocorrência de parâmetro em seqüência de caracteres de substituição com o argumento correspondente no código-fonte e, em seguida, substitui nome da dica com seqüência de caracteres de substituição.
@<	Um determinado arquivo de dicas seqüência de caracteres de substituição que indica o início de um conjunto de elementos do mapa.
@=	Um determinado arquivo de dicas seqüência de caracteres de substituição indica um elemento do mapa intermediário.Um mapa pode ter vários elementos do mapa.
@>	Um determinado arquivo de dicas seqüência de caracteres de substituição que indica o final de um conjunto de elementos do mapa.
#undefnome da dica	A diretiva de pré-processador que exclui uma dica existente.O nome da dica é fornecido pelo nome da dica identificador.
//comentário	Um comentário de linha única.
/*comentário*/	Um comentário de várias linhas.

O que Macros exigem uma dica?

Certos tipos de macros podem interferir com o sistema de análise.Esta seção descreve os tipos de macros que podem causar um problema e o tipo de dica que você pode criar para resolver esse problema.

Macros de interrupções

Algumas macros fazem com que o sistema de análise interpretem o código-fonte, mas podem ser ignoradas sem comprometer a sua experiência de navegação.Por exemplo, o (linguagem de anotação de código fonteSAL) macros resolvem para atributos de C++ que ajudarão-lo a encontrar bugs de programação.Se você deseja ignorar as anotações de SAL como procurar código, talvez queira criar um arquivo de dica que oculta a anotação.

No seguinte código-fonte, o parâmetro de tipo para o FormatWindowClassName() é função PXSTR, e é o nome do parâmetro szBuffer.No entanto, os erros de sistema de análise de _Pre_notnull_ e _Post_z_ Anotações de SAL para o tipo de parâmetro ou o nome do parâmetro.

Código-fonte:

FormatWindowClassName void estático(_Pre_notnull_ _Post_z_ PXSTR szBuffer)

Estratégia: Definição de NULL

A estratégia nessa situação é tratar as anotações de SAL como se eles não existissem.Para fazer isso, especifique uma dica cuja seqüência de caracteres de substituição é nula.Conseqüentemente, o sistema de análise ignora as anotações e o Modo de exibição de classe navegador não exibi-los.(Visual C++ inclui um arquivo de dica interna que oculta a anotação de SAL.)

Arquivo de dicas:

#define _Pre_notnull_

Elementos de linguagem C/C++ escondido

Um motivo comum que o sistema de análise interpreta erroneamente código-fonte é se uma macro oculta um C/C++ pontuador ou palavra-chave token.Ou seja, uma macro pode conter metade de um par de pontuadores, como <>, [], {}, e ().

No seguinte código-fonte, o START_NAMESPACE macro oculta um (sem paridade chave esquerda{).

Código-fonte:

#define START_NAMESPACE namespace MyProject {

Estratégia: Cópia direta

Se a semântica de uma macro é essencial para a experiência de navegação, crie uma dica que é idêntica à macro.O sistema de análise resolve a macro para a definição no arquivo de dica.

Observe que, se a macro no arquivo de origem contém outras macros, as macros são interpretadas somente se eles já estão no conjunto de dicas eficazes.

Arquivo de dicas:

#define START_NAMESPACE namespace MyProject {

Mapas

Consiste em um mapa de macros que designa um elemento inicial, o elemento final e zero ou mais elementos intermediários.O sistema de análise interpreta erroneamente mapas porque cada macro mapa oculta os elementos de linguagem C/C++ e a sintaxe de uma instrução completa do C/C++ é distribuída entre muitos macros separadas.

O seguinte código de origem define o BEGIN_CATEGORY_MAP, IMPLEMENTED_CATEGORY, e END_CATEGORY_MAP macros.

Código-fonte:

#define BEGIN_CATEGORY_MAP(x)\
static const struct ATL::_ATL_CATMAP_ENTRY* GetCategoryMap() throw() {\
static const struct ATL::_ATL_CATMAP_ENTRY pMap[] = {
#define IMPLEMENTED_CATEGORY( catid ) { _ATL_CATMAP_ENTRY_IMPLEMENTED, &catid },
#define END_CATEGORY_MAP()\
   { _ATL_CATMAP_ENTRY_END, NULL } };\
   return( pMap ); }

Estratégia: Identificar elementos de mapa

Dicas para o início, o meio (se houver) e o fim de especificar os elementos de um mapa.Usar as seqüências de caracteres de substituição de mapa especial @<, @=, e @>.Para obter mais informações, consulte o Sintaxe seção neste tópico.

Arquivo de dicas:

// Start of the map.
#define BEGIN_CATEGORY_MAP(x) @<
// Intermediate map element.
#define IMPLEMENTED_CATEGORY( catid ) @=
// Intermediate map element.
#define REQUIRED_CATEGORY( catid ) @=
// End of the map.
#define END_CATEGORY_MAP() @>

Macros compostas

Macros compostas contém um ou mais dos tipos de macro que confundir o sistema de análise.

O seguinte código-fonte contém o START_NAMESPACE macro, que especifica o início de um escopo de namespace, e o BEGIN_CATEGORY_MAP macro, que especifica o início de um mapa.

Código-fonte:

#define NSandMAP START_NAMESPACE BEGIN_CATEGORY_MAP

Estratégia: Cópia direta

Criar dicas para o START_NAMESPACE e BEGIN_CATEGORY_MAP macros e, em seguida, criar uma dica para o NSandMAP macro que é o mesmo mostrado anteriormente para o código-fonte.Como alternativa, se uma macro composta consiste somente macros de interrupções e espaço em branco, você pode definir uma dica cuja seqüência de caracteres de substituição é uma definição de null.

Neste exemplo, suponha que START_NAMESPACE já tem uma dica, conforme descrito neste tópico na Elementos de linguagem C/C++ escondido subtítulo.E suponha que BEGIN_CATEGORY_MAP tem uma dica, conforme descrito anteriormente Mapas.

Arquivo de dicas:

#define NSandMAP START_NAMESPACE BEGIN_CATEGORY_MAP

Macros inconvenientes

Algumas macros podem ser interpretadas pelo sistema de análise, mas o código-fonte é difícil de ler porque a macro é longa ou complexa.Para facilitar a leitura, você pode fornecer uma dica que simplifica a exibição da macro.

Código-fonte:

#define STDMETHOD(methodName) HRESULT (STDMETHODCALLTYPE * methodName)

Estratégia: Simplificação

Crie uma dica que exibe uma definição mais simples de macro.

Arquivo de dicas:

#define STDMETHOD(methodName) void* methodName

Exemplo

O exemplo a seguir ilustra como as dicas são acumuladas dos arquivos de dica.Arquivos de parada não são usados neste exemplo.

A ilustração a seguir mostra alguns dos diretórios físicos em um projeto do Visual C++.Dica arquivos estão na vcpackages, Debug, A1, e A2 diretórios.

Diretórios de arquivo de dica

Diretórios e o conteúdo do arquivo de dica

A tabela a seguir lista 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 vcpackages arquivo de dicas de diretório são listados.

Diretório	Conteúdo do arquivo de dica
vcpackages	// vcpackages (partial list) #define _In_ #define _In_opt_ #define _In_z_ #define _In_opt_z_ #define _In_count_(size)
Debug	// 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

A tabela a seguir lista as dicas eficazes para os arquivos de origem neste projeto.

Arquivo de origem	Dicas eficazes
A1_A2_B.cpp	// 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 }

As observações a seguir se aplicam a tabela anterior.

• As dicas eficazes são da vcpackages, Debug, A1, e A2 diretórios.

• O #undef diretiva na Debug arquivo de dicas removido o #define _In_ dica na vcpackages arquivo de dicas de diretório.

• O arquivo de dica na A1 Redefine o diretório START_NAMESPACE.

• O #undef dica na A2 Dicas para remover da pasta OBRACE e CBRACE no Debug arquivo de dicas de diretório.

Consulte também

Referência

Diretiva #define (C/C++)

Diretiva #undef (C/C++)

Mapas de mensagem (MFC)

Conceitos

Tipos de arquivo criados para projetos do Visual C++

Anotações de SAL

Outros recursos

Criando e controlando janelas de ambiente

Mensagem mapa Macros (ATL)

Objeto mapa Macros