Annotieren des Funktionsverhaltens

  • Artikel

Zusätzlich zum Kommentieren von Funktionsparametern und Rückgabewerten können Sie Eigenschaften der gesamten Funktion kommentieren.

Funktionsanmerkungen

Die folgenden Anmerkungen gelten für die Funktion als Ganzes und beschreiben, wie sie sich verhält oder was sie erwartet, wahr zu sein.

Anmerkung Beschreibung
_Called_from_function_class_(name) Nicht dazu gedacht, eigenständig zu sein; Stattdessen ist es ein Prädikat, das mit der _When_ Anmerkung verwendet werden soll. Weitere Informationen finden Sie unter Angeben von Wann und Wo eine Anmerkung gilt.

Der name Parameter ist eine beliebige Zeichenfolge, die auch in einer _Function_class_ Anmerkung in der Deklaration einiger Funktionen angezeigt wird. _Called_from_function_class_ gibt "nonzero" zurück, wenn die aktuell analysierte Funktion mit _Function_class_ demselben Wert versehen nameist. Andernfalls wird Null zurückgegeben.
_Check_return_ Kommentiert einen Rückgabewert und gibt an, dass der Aufrufer ihn prüfen soll. Die Überprüfung meldet einen Fehler, wenn die Funktion in einem ungültigen Kontext aufgerufen wird.
_Function_class_(name) Der name Parameter ist eine beliebige Zeichenfolge, die vom Benutzer festgelegt wird. Es ist in einem Namespace vorhanden, der sich von anderen Namespaces unterscheidet. Eine Funktion, ein Funktionszeiger oder – am nützlichsten – ein Funktionszeigertyp kann als Zugehörigkeit zu einer oder mehreren Funktionsklassen festgelegt werden.
_Raises_SEH_exception_ Kommentiert eine Funktion, die immer eine strukturierte Ausnahmehandler-Ausnahme (SEH) auslöst, vorbehaltlich _When_ und _On_failure_ Bedingungen. Weitere Informationen finden Sie unter Angeben von Wann und Wo eine Anmerkung gilt.
_Maybe_raises_SEH_exception_ Kommentiert eine Funktion, die optional eine SEH-Ausnahme auslösen kann, vorbehaltlich _When_ und _On_failure_ Bedingungen.
_Must_inspect_result_ Kommentiert alle Ausgabewerte, einschließlich des Rückgabewerts, der Parameter und der Globalen. Der Analysebericht meldet einen Fehler, wenn der Wert im kommentierten Objekt anschließend nicht überprüft wird. "Inspektion" enthält, ob sie in einem bedingten Ausdruck verwendet wird, einem Ausgabeparameter oder global zugewiesen oder als Parameter übergeben wird. Für Rückgabewerte _Must_inspect_result_ impliziert _Check_return_.
_Use_decl_annotations_ Kann anstelle der Liste der Anmerkungen in der Kopfzeile in einer Funktionsdefinition (auch als Funktionstext bezeichnet) verwendet werden. Wenn _Use_decl_annotations_ sie verwendet werden, werden die Anmerkungen, die in einem Bereichsheader für dieselbe Funktion angezeigt werden, verwendet, als ob sie auch in der Definition vorhanden sind, die die _Use_decl_annotations_ Anmerkung enthält.

Erfolgs-/Fehleranmerkungen

Eine Funktion kann fehlschlagen, und wenn dies der Fall ist, sind die Ergebnisse möglicherweise unvollständig oder unterscheiden sich von den Ergebnissen, wenn die Funktion erfolgreich ist. Die Anmerkungen in der folgenden Liste bieten Möglichkeiten, das Fehlerverhalten auszudrücken. Um diese Anmerkungen zu verwenden, müssen Sie es ihnen ermöglichen, den Erfolg zu bestimmen; daher ist eine _Success_ Anmerkung erforderlich. Beachten Sie, dass NTSTATUS und bereits eine _Success_ Anmerkung integriert ist. Wenn Sie jedoch Ihre eigene _Success_ Anmerkung NTSTATUS angeben oderHRESULT, wird die integrierte Anmerkung HRESULT außer Kraft gesetzt.

Anmerkung Beschreibung
_Always_(anno_list) anno_list _On_failure_(anno_list)Entspricht ; d. h. die Anmerkungenanno_list, die angewendet werden, ob die Funktion erfolgreich ist.
_On_failure_(anno_list) Wird nur verwendet, wenn _Success_ sie auch zum Kommentieren der Funktion verwendet wird – entweder explizit oder implizit über _Return_type_success_ eine Typedef. Wenn die _On_failure_ Anmerkung für einen Funktionsparameter oder Rückgabewert vorhanden ist, verhält sich jede Anmerkung in anno_list (anno) so, als wäre sie codiert als _When_(!expr, anno), wobei expr der Parameter für die erforderliche _Success_ Anmerkung steht. Dies bedeutet, dass die konkludente Anwendung auf _Success_ alle Nachbedingungen nicht gilt _On_failure_.
_Return_type_success_(expr) Kann auf einen Typedef angewendet werden. Gibt an, dass alle Funktionen, die diesen Typ zurückgeben und nicht explizit _Success_ haben, als ob sie _Success_(expr)vorhanden sind. _Return_type_success_ kann nicht für eine Funktion oder einen Funktionszeigertyp verwendet werden.
_Success_(expr) expr ist ein Ausdruck, der einen Wert zurückgibt. Wenn die _Success_ Anmerkung in einer Funktionsdeklaration oder -definition vorhanden ist, verhält sich jede Anmerkung (anno) für die Funktion und in postbedingung so, als wäre sie codiert als _When_(expr, anno). Die _Success_ Anmerkung kann nur für eine Funktion verwendet werden, nicht für die Parameter oder den Rückgabetyp. Es kann höchstens eine _Success_ Anmerkung für eine Funktion geben, und sie darf nicht in einem _When_, oder _At__Group_. Weitere Informationen finden Sie unter Angeben von Wann und Wo eine Anmerkung gilt.

Siehe auch