関数の動作に注釈を付ける

  • [アーティクル]

関数のパラメーターと戻り値に注釈を付けるだけでなく、関数全体のプロパティに注釈を付けることもできます。

関数の注釈

次の注釈は、関数全体に適用され、関数がどのように動作するか、どうすれば true になるを説明しています。

注釈 説明
_Called_from_function_class_(name) スタンド アロンを意図したものではありません。代わりに、_When_ の注釈で使用される述語です。 詳細については、「注釈を適用するタイミングと場所の指定」を参照してください。

name パラメーターは、一部の関数の宣言内の _Function_class_ の注釈にも含まれる任意の文字列です。 現在分析されている関数が name と同じ値を持つ _Function_class_ を使用して注釈を付けられている場合、_Called_from_function_class_ はゼロ以外の値を返します。それ以外の場合はゼロを返します。
_Check_return_ 戻り値に注釈を付け、呼び出し元がそれを検査する必要があることを示します。 関数が void コンテキストで呼び出された場合、チェッカーはエラーを報告します。
_Function_class_(name) name パラメーターは、ユーザーが指定する任意の文字列です。 これは、他の名前空間と別の名前空間に存在します。 関数、関数ポインター、または (最も便利な) 関数ポインター型は、1 つまたは複数の関数クラスに属しているものとして指定できます。
_Raises_SEH_exception_ _When_ および _On_failure_ の条件に従って、常に構造化例外ハンドラー (SEH) 例外を発生させる関数に注釈を適用します。 詳細については、「注釈を適用するタイミングと場所の指定」を参照してください。
_Maybe_raises_SEH_exception_ _When_ および _On_failure_ の条件に従って、必要に応じて SEH 例外を発生させる可能性がある関数に注釈を適用します。
_Must_inspect_result_ 戻り値、パラメーター、およびグローバルを含む、任意の出力値に注釈を付けます。 アナライザーは、注釈付きオブジェクトの値がその後検査されない場合にエラーを報告します。 "検査" には、条件式で使用されるか、出力パラメーターまたはグローバルに割り当てられるか、またはパラメーターとして渡されるかが含まれます。 戻り値の場合、_Must_inspect_result_ は_Check_return_ を暗黙に示しています。
_Use_decl_annotations_ ヘッダー内の注釈のリストの代わりに、関数定義 (関数本体とも呼ばれる) で使用できます。 _Use_decl_annotations_ を使用する場合、同じ関数のスコープ内ヘッダーに表示される注釈は、_Use_decl_annotations_ の注釈を持つ定義内にも存在するかのように使用されます。

成功または失敗の注釈

関数が失敗することがあり、失敗した場合、結果が不完全になるか、関数が成功したときの結果と異なる場合があります。 次の一覧の注釈は、失敗の動作を表現する方法を示しています。 これらの注釈を使用するには、成功したかどうかを判断するために注釈を有効にする必要があります。したがって、_Success_ の注釈が必要です。 NTSTATUS と HRESULT には既に _Success_ の注釈が組み込まれています。ただし、NTSTATUS または HRESULT で独自の _Success_ の注釈を指定すると、組み込みの注釈がオーバーライドされます。

注釈 説明
_Always_(anno_list) anno_list _On_failure_(anno_list) と同じです。つまり、関数が成功したかどうかにかかわらず、anno_list 内の注釈が適用されます。
_On_failure_(anno_list) _Success_ が関数に注釈を付けるためにも使用される場合にのみ使用されます。明示的に、または typedef の _Return_type_success_ を介して暗黙的にも使用されます。 関数パラメーターまたは戻り値に _On_failure_ の注釈が存在する場合、anno_list (注釈) の各注釈は _When_(!expr, anno) としてコード化されているかのように動作します。ここで、expr は必要な _Success_ の注釈のパラメーターです。 これは、すべての事後条件に対する暗黙の _Success_ の適用が _On_failure_ に適用されないことを意味します。
_Return_type_success_(expr) Typedef に適用される可能性があります。 この型を返し、明示的に _Success_ を持たないすべての関数に、_Success_(expr) があるかのように注釈が付けられることを示します。 _Return_type_success_ は、関数または関数ポインター typedef では使用できません。
_Success_(expr) expr は rvalue を生成する式です。 _Success_ の注釈が関数宣言または定義に存在する場合、関数および事後条件の各注釈 (anno) は、_When_(expr, anno) としてコード化されているかのように動作します。 _Success_ の注釈は、そのパラメーターや戻り値の型ではなく、関数でのみ使用できます。 関数には最大 1 つの _Success_ の注釈を付けることができます。_When_、_At_、_Group_ には付けることができません。 詳細については、「注釈を適用するタイミングと場所の指定」を参照してください。

関連項目