Soubory pokynů

Soubor nápovědy obsahuje makra, která by jinak způsobila vynechání oblastí kódu analyzátorem databáze procházení C++. Když otevřete projekt Visual Studio C++, analyzátor analyzuje kód v každém zdrojovém souboru v projektu a sestaví databázi s informacemi o každém identifikátoru. Integrované vývojové prostředí (IDE) tyto informace používá k podpoře funkcí procházení kódu, jako je prohlížeč zobrazení tříd a navigační panel.

Analyzátor databáze procházení C++ je přibližný analyzátor, který dokáže parsovat velké množství kódu za krátkou dobu. Jedním z důvodů, proč je rychlý, je to proto, že přeskočí obsah bloků. Například zaznamenává pouze umístění a parametry funkce a ignoruje jeho obsah. Některá makra můžou způsobit problémy s heuristikou používanou k určení začátku a konce bloku. Tyto problémy způsobují nesprávné zaznamenání oblastí kódu.

Tyto přeskočené oblasti se můžou projevit několika způsoby:

• Chybějící typy a funkce v zobrazení tříd, Přejít na a navigační panel

• Nesprávné obory v navigačním panelu

• Návrhy k vytvoření deklarace nebo definice pro funkce, které jsou již definovány

Soubor nápovědy obsahuje uživatelsky přizpůsobitelné rady, které mají stejnou syntaxi jako definice maker C/C++. Visual C++ obsahuje integrovaný soubor nápovědy, který je dostatečný pro většinu projektů. Můžete ale vytvořit vlastní soubory nápovědy pro vylepšení analyzátoru speciálně pro váš projekt.

Důležité

Pokud upravíte nebo přidáte soubor nápovědy, musíte provést další kroky, aby se změny projevily:

• Ve verzích před sadou Visual Studio 2017 verze 15.6: Odstraňte soubor .sdf nebo VC.db v řešení pro všechny změny.
• V sadě Visual Studio 2017 verze 15.6 a novějších verzích: Po přidání nových souborů nápovědy zavřete a znovu otevřete řešení.

Scénář

#define NOEXCEPT noexcept
void Function() NOEXCEPT
{
}

Bez souboru Function nápovědy se nezobrazuje v zobrazení třídy, přejít na nebo navigační panel. Po přidání souboru nápovědy s touto definicí makra teď analyzátor rozumí a nahrazuje NOEXCEPT makro, což mu umožní správně analyzovat funkci:

#define NOEXCEPT

Rušivé makra

Existují dvě kategorie maker, které naruší analyzátor:

• Makra, která zapouzdřují klíčová slova, která jsou doplňkem funkce

  #define NOEXCEPT noexcept
  #define STDMETHODCALLTYPE __stdcall
  

  U těchto typů maker se v souboru nápovědy vyžaduje pouze název makra:

  #define NOEXCEPT
  #define STDMETHODCALLTYPE
  

• Makra, která obsahují nevyvážené závorky

  #define BEGIN {
  

  U těchto typů maker se v souboru nápovědy vyžaduje název makra i jeho obsah:

  #define BEGIN {
  

Podpora editoru

Od sady Visual Studio 2017 verze 15.8 existuje několik funkcí pro identifikaci rušivých maker:

• Makra, která jsou uvnitř oblastí přeskočená analyzátorem, jsou zvýrazněná.

• Existuje rychlá akce k vytvoření souboru nápovědy, který obsahuje zvýrazněné makro nebo pokud existuje soubor nápovědy, který makro přidá do souboru nápovědy.

Po provedení některé z rychlých akcí analyzátor reparsuje soubory ovlivněné souborem nápovědy.

Ve výchozím nastavení je makro problému zvýrazněno jako návrh. Zvýraznění lze změnit na něco výraznějšího, například červené nebo zelené vlnovku. V části Nástroje Možnosti>>textového editoru>C/C++>View použijte makra v části Přeskočené oblasti procházení vlnovkou kódu.

Zobrazení chyb databáze procházení

Příkaz nabídky Chyby procházení databáze zobrazení projektu>zobrazí všechny oblasti, které se nepodařilo analyzovat v seznamu chyb. Příkaz je určený ke zjednodušení vytváření počátečního souboru nápovědy. Analyzátor ale nedokáže zjistit, jestli příčinou chyby bylo rušivé makro, takže je nutné vyhodnotit každou chybu. Spusťte příkaz Zobrazit chyby databáze procházení a přejděte na každou chybu a načtěte ovlivněný soubor v editoru. Po načtení souboru se zvýrazní některá makra v oblasti. Rychlé akce můžete vyvolat a přidat je do souboru nápovědy. Po aktualizaci souboru nápovědy se seznam chyb aktualizuje automaticky. Pokud soubor nápovědy upravujete ručně, můžete k aktivaci aktualizace použít příkaz Znovu prohledat řešení .

Architektura

Soubory nápovědy se vztahují k fyzickým adresářům, nikoli logickým adresářům zobrazeným v Průzkumník řešení. Nemusíte do projektu přidávat soubor nápovědy, aby se soubor nápovědy projevil. Systém analýzy používá soubory nápovědy pouze při analýze zdrojových souborů.

Každý soubor nápovědy má název cpp.hint. Mnoho adresářů může obsahovat soubor nápovědy, ale v určitém adresáři může dojít pouze k jednomu souboru nápovědy.

Projekt může mít vliv na nula nebo více souborů nápovědy. Pokud neexistují žádné soubory nápovědy, analyzátor používá techniky obnovení chyb k ignorování nešifrovatelného zdrojového kódu. V opačném případě systém analýzy používá následující strategii k vyhledání a shromáždění tipů.

Pořadí hledání

Analýza systému hledá v adresářích soubory nápovědy v následujícím pořadí.

• Adresář, který obsahuje instalační balíček pro Visual C++ (vcpackages). Tento adresář obsahuje integrovaný soubor nápovědy, který popisuje symboly v často používaných systémových souborech, například windows.h. V důsledku toho váš projekt automaticky dědí většinu tipů, které potřebuje.

• Cesta z kořenového adresáře zdrojového souboru do adresáře, který obsahuje samotný zdrojový soubor. V typickém projektu visual Studio C++ obsahuje kořenový adresář soubor řešení nebo projektu.

  Výjimkou tohoto pravidla je, pokud je soubor stop v cestě ke zdrojovému souboru. Soubor stop je libovolný soubor s názvem cpp.stop. Soubor stop poskytuje další kontrolu nad pořadím hledání. Namísto spuštění z kořenového adresáře prohledá systém analýzu ze adresáře, který obsahuje soubor stop, do adresáře, který obsahuje zdrojový soubor. V typickém projektu nepotřebujete soubor stop.

Shromažďování tipů

Soubor nápovědy obsahuje nula nebo více tipů. Tip se definuje nebo odstraní stejně jako makro C/C++. To znamená, že direktiva preprocesoru #define vytvoří nebo předefinuje nápovědu a #undef direktiva odstraní nápovědu.

Systém analýzy otevře každý soubor nápovědy v pořadí hledání popsaném výše. Shromažďuje rady jednotlivých souborů do sady efektivních tipů a pak pomocí efektivních tipů interpretuje identifikátory ve vašem kódu.

Systém analýzy používá tato pravidla k nahromadění tipů:

• Pokud nový tip určuje název, který ještě není definovaný, přidá nový tip název do efektivních tipů.

• Pokud nový tip určuje název, který je již definován, nový tip předefinuje existující nápovědu.

• Pokud je nový tip direktivou #undef , která určuje existující efektivní nápovědu, nová nápověda odstraní existující nápovědu.

První pravidlo znamená, že efektivní rady se dědí z dříve otevřených souborů nápovědy. Poslední dvě pravidla znamenají, že nápovědy později v pořadí hledání mohou přepsat dřívější nápovědy. Pokud například vytvoříte soubor nápovědy v adresáři, který obsahuje zdrojový soubor, můžete přepsat všechny předchozí rady.

Informace o tom, jak se shromažďují rady, najdete v části Příklad .

Syntaxe

Nápovědy vytvoříte a odstraníte pomocí stejné syntaxe jako direktivy preprocesoru pro vytváření a odstraňování maker. Ve skutečnosti systém analýzy používá preprocesor C/C++ k vyhodnocení nápovědy. Další informace o direktivách preprocesoru najdete v tématech #define – direktiva (C/C++) a #undef – direktiva (C/C++).

Jedinými neobvyklými prvky syntaxe jsou @<řetězce , @=a @> náhradní řetězce. Tyto náhradní řetězce specifické pro soubor nápovědy se používají pouze v makrech mapování . Mapa je sada maker, která souvisejí s daty, funkcemi nebo událostmi s jinými daty, funkcemi nebo obslužné rutiny událostí. Například MFC pomocí map map zpráv vytváří mapy a ATL mapy používá k vytváření map objektů. Náhradní řetězce specifické pro soubor nápovědy označují počáteční, přechodné a koncové prvky mapy. Význam má jenom název mapového makra. Proto každý náhradní řetězec záměrně skryje implementaci makra.

Nápovědy používají tuto syntaxi:

Syntaxe	Význam
#definehint-name náhradní řetězec #definehint-name ( parametr, ...)náhradní řetězec	Direktiva preprocesoru, která definuje nový tip nebo předefinuje existující nápovědu. Po direktivě nahradí preprocesor každý výskyt názvu nápovědy ve zdrojovém kódu řetězcem replace-string. Druhý formát syntaxe definuje nápovědu typu funkce. Pokud ve zdrojovém kódu dojde k nápovědě podobné funkci, preprocesor nejprve nahradí každý výskyt parametru v náhradním řetězci odpovídajícím argumentem ve zdrojovém kódu a nahradí název nápovědy náhradním řetězcem.
@<	Řetězec pro nahrazení specifický pro soubor nápovědy, který označuje začátek sady prvků mapy.
@=	Řetězec nahrazení specifický pro soubor nápovědy, který označuje zprostředkující prvek mapování. Mapa může mít více prvků mapování.
@>	Řetězec nahrazení specifický pro soubor nápovědy, který označuje konec sady prvků mapy.
#undefhint-name	Direktiva preprocesoru, která odstraní existující nápovědu. Název nápovědy je poskytován identifikátorem hint-name .
//komentář	Jednořádkový komentář.
/*komentář */	Víceřádkový komentář.

Příklad

Tento příklad ukazuje, jak se nápovědy hromadí ze souborů nápovědy. V tomto příkladu se soubory stop nepoužívají.

Obrázek znázorňuje některé fyzické adresáře v projektu Visual Studio C++. Soubory nápovědy vcpackagesjsou v adresářích , A1Debug, a A2 adresáře.

Adresáře souborů nápovědy

Adresáře a obsah souboru nápovědy

Tento seznam zobrazuje adresáře v tomto projektu, které obsahují soubory nápovědy, a obsah těchto souborů nápovědy. V souboru nápovědy vcpackages adresáře jsou uvedené pouze některé z mnoha tipů:

• balíčky vcpackages

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

• Ladění

  // 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
  

Efektivní rady

Tato tabulka uvádí efektivní rady pro zdrojové soubory v tomto projektu:

• Zdrojový soubor: A1_A2_B.cpp

• Efektivní rady:

  // 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 }
  

Tyto poznámky platí pro předchozí seznam:

• Účinné rady jsou z vcpackagesadresáře , Debug, A1a A2 adresáře.

• Direktiva #undef v Debug souboru nápovědy odebrala nápovědu vcpackages #define _In_ v souboru nápovědy adresáře.

• Soubor nápovědy v adresáři A1 předefinuje START_NAMESPACE.

• Nápověda #undef v A2 adresáři odebrala rady pro OBRACE a CBRACE v Debug souboru nápovědy adresáře.

Viz také

Typy souborů vytvořené pro projekty Visual Studio C++
#define – direktiva (C++)
#undef – direktiva (C++)
Poznámky SAL