Sdílet prostřednictvím

Přidávání poznámek k chování funkce

  • Článek

Kromě přidávání poznámek k parametrům funkce a návratových hodnot můžete také anotovat vlastnosti celé funkce.

Poznámky k funkcím

Následující poznámky platí pro funkci jako celek a popisují, jak se chová nebo co očekává, že bude pravdivá.

Poznámka Popis
_Called_from_function_class_(name) Nemělo by stát sám; místo toho je predikát, který se má použít s poznámkou _When_ . Další informace naleznete v tématu Určení kdy a kde se má anotaci použít.

Parametr name je libovolný řetězec, který se také zobrazí v _Function_class_ poznámce v deklaraci některých funkcí. _Called_from_function_class_ vrátí nenulovou hodnotu, pokud je funkce, která je aktuálně analyzována, opatřena poznámkami, která _Function_class_ má stejnou hodnotu name; v opačném případě vrátí nulu.
_Check_return_ Anotuje návratovou hodnotu a uvádí, že volající by ji měl zkontrolovat. Kontrola hlásí chybu, pokud je funkce volána v kontextu void.
_Function_class_(name) Parametr name je libovolný řetězec určený uživatelem. Existuje v oboru názvů, který se liší od ostatních oborů názvů. Funkce, ukazatel funkce nebo nejužitečnější typ ukazatele funkce může být určen jako patří do jedné nebo více tříd funkcí.
_Raises_SEH_exception_ Anotuje funkci, která vždy vyvolává výjimku strukturované obslužné rutiny výjimek (SEH), s _When_ výhradou a _On_failure_ podmínkami. Další informace naleznete v tématu Určení kdy a kde se má anotaci použít.
_Maybe_raises_SEH_exception_ Anotuje funkci, která může volitelně vyvolat výjimku SEH, s _When_ výhradou a _On_failure_ podmínkami.
_Must_inspect_result_ Anotuje libovolnou výstupní hodnotu, včetně návratové hodnoty, parametrů a globálních hodnot. Analyzátor hlásí chybu, pokud hodnota v anotovaném objektu není následně zkontrolována. Kontrola zahrnuje, jestli se používá v podmíněném výrazu, je přiřazený k výstupnímu parametru nebo globálnímu parametru nebo je předán jako parametr. Pro návratové hodnoty napovídá _Must_inspect_result__Check_return_.
_Use_decl_annotations_ Lze použít u definice funkce (označované také jako tělo funkce) místo seznamu poznámek v záhlaví. Při _Use_decl_annotations_ použití se použijí poznámky, které se zobrazí v záhlaví v oboru pro stejnou funkci, jako by se vyskytovaly také v definici, která má poznámku _Use_decl_annotations_ .

Poznámky k úspěchu nebo selhání

Funkce může selhat a pokud ano, její výsledky můžou být neúplné nebo se liší od výsledků, když bude funkce úspěšná. Poznámky v následujícím seznamu poskytují způsoby vyjádření chování selhání. Chcete-li tyto poznámky použít, musíte jim umožnit určit úspěch; anotace je proto povinná _Success_ . Všimněte si, že NTSTATUS a HRESULT už do nich máte integrovanou poznámku_Success_. Pokud ale zadáte vlastní _Success_ poznámku nebo HRESULT, přepíše předdefinované poznámkyNTSTATUS.

Poznámka Popis
_Always_(anno_list) anno_list _On_failure_(anno_list)To znamená, že poznámky se anno_list použijí bez ohledu na to, zda je funkce úspěšná.
_On_failure_(anno_list) Chcete-li použít pouze tehdy, když _Success_ se používá také k přidávání poznámek funkce – buď explicitně, nebo implicitně prostřednictvím _Return_type_success_ typedef. _On_failure_ Pokud je poznámka přítomna u parametru funkce nebo návratové hodnoty, každá poznámka v anno_list (anno) se chová, jako by byla zakódovaná jako _When_(!expr, anno), kde expr je parametr požadované _Success_ poznámky. To znamená, že implicitní použití _Success_ pro všechny po-podmínky se nevztahuje na _On_failure_.
_Return_type_success_(expr) Lze použít u definice typedef. Označuje, že všechny funkce, které vracejí tento typ a nemají explicitně _Success_ , jsou opatřeny poznámkami, jako by měly _Success_(expr). _Return_type_success_ nelze použít u funkce nebo u ukazatele funkce.
_Success_(expr) expr je výraz, který dává hodnotu rvalue. _Success_ Pokud je poznámka přítomna v deklaraci nebo definici funkce, každá poznámka (anno) funkce a v post-condition se chová, jako by byla kódována jako _When_(expr, anno). Anotaci _Success_ lze použít pouze u funkce, ne u jejích parametrů nebo návratového typu. Funkce může obsahovat maximálně jednu _Success_ poznámku, která nemůže být v žádném _When_objektu , _At_nebo _Group_. Další informace naleznete v tématu Určení kdy a kde se má anotaci použít.

Viz také