Kommentieren des Funktionsverhaltens

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.

Anmerkung BESCHREIBUNG
_Called_from_function_class_(name) Nicht als eigenständig vorgesehen; Stattdessen ist es ein Prädikat, das mit der _When_ Anmerkung verwendet werden soll. Weitere Informationen finden Sie unter Angeben, wann und wo eine Anmerkung angewendet wird.

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 einen Wert ungleich 0 (null) zurück, wenn die Funktion, die gerade analysiert wird, mit anmerkungent wird, indem verwendet _Function_class_ wird, die den gleichen Wert von nameauf hat. Andernfalls wird 0 (null) zurückgegeben.
_Check_return_ Kommentiert einen Rückgabewert und gibt an, dass der Aufrufer ihn überprüfen soll. Die Überprüfung meldet einen Fehler, wenn die Funktion in einem void-Kontext aufgerufen wird.
_Function_class_(name) Der name -Parameter ist eine beliebige Zeichenfolge, die vom Benutzer festgelegt wird. Sie ist in einem Namespace vorhanden, der sich von anderen Namespaces unterscheidet. Eine Funktion, ein Funktionszeiger oder – besonders nützlich – ein Funktionszeigertyp kann als zu einer oder mehreren Funktionsklassen gehörend festgelegt werden.
_Raises_SEH_exception_ Kommentiert eine Funktion, die unter den _When_ Bedingungen und _On_failure_ immer eine SEH-Ausnahme (Structured Exception Handler) auslöst. Weitere Informationen finden Sie unter Angeben, wann und wo eine Anmerkung angewendet wird.
_Maybe_raises_SEH_exception_ Kommentiert eine Funktion, die optional eine SEH-Ausnahme auslösen kann, unter den _When_ Bedingungen und _On_failure_ .
_Must_inspect_result_ Kommentiert alle Ausgabewerte, einschließlich Rückgabewert, Parameter und globale Werte. Das Analyseprogramm meldet einen Fehler, wenn der Wert im kommentierten Objekt anschließend nicht überprüft wird. "Inspection" umfasst, ob sie in einem bedingten Ausdruck verwendet, einem Ausgabeparameter oder global zugewiesen oder als Parameter übergeben wird. Für Rückgabewerte _Must_inspect_result_ impliziert _Check_return_.
_Use_decl_annotations_ Kann für eine Funktionsdefinition (auch als Funktionstext bezeichnet) anstelle der Liste der Anmerkungen im Header verwendet werden. Wenn _Use_decl_annotations_ verwendet wird, werden die Anmerkungen, die in einem Bereichsheader für dieselbe Funktion angezeigt werden, so verwendet, als wären sie auch in der Definition vorhanden, die die _Use_decl_annotations_ Anmerkung enthält.

Erfolgs-/Fehleranmerkungen

Eine Funktion kann fehlschlagen, und wenn sie dies tut, können ihre Ergebnisse unvollständig sein oder sich von den Ergebnissen unterscheiden, wenn die Funktion erfolgreich ausgeführt wird. Die Anmerkungen in der folgenden Liste bieten Möglichkeiten, das Fehlerverhalten auszudrücken. Um diese Anmerkungen zu verwenden, müssen Sie sie aktivieren, um den Erfolg zu bestimmen. daher ist eine _Success_ Anmerkung erforderlich. Beachten Sie, dass NTSTATUS und HRESULT bereits über eine _Success_ integrierte Anmerkung verfügen. Wenn Sie jedoch ihre eigene _Success_ Anmerkung für NTSTATUS oder HRESULTangeben, überschreibt sie die integrierte Anmerkung.

Anmerkung BESCHREIBUNG
_Always_(anno_list) anno_list _On_failure_(anno_list)Entspricht ; das heißt, die Anmerkungen in anno_list gelten unabhängig davon, ob die Funktion erfolgreich ist.
_On_failure_(anno_list) Wird nur verwendet, wenn _Success_ auch verwendet wird, um die Funktion zu kommentieren – entweder explizit oder implizit durch _Return_type_success_ in einer 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 als _When_(!expr, anno)codiert, wobei expr der Parameter für die erforderliche _Success_ Anmerkung ist. Dies bedeutet, dass die implizite Anwendung von _Success_ auf alle Nachbedingungen nicht für _On_failure_gilt.
_Return_type_success_(expr) Kann auf eine TypeDef angewendet werden. Gibt an, dass alle Funktionen, die diesen Typ zurückgeben und nicht explizit besitzen _Success_ , mit Anmerkungen versehen werden, als ob sie hätten _Success_(expr). _Return_type_success_ kann nicht für eine Funktion oder funktionszeigertypdefinition verwendet werden.
_Success_(expr) expr ist ein Ausdruck, der einen rvalue ergibt. Wenn die _Success_ Anmerkung in einer Funktionsdeklaration oder -definition vorhanden ist, verhält sich jede Anmerkung (anno) in der Funktion und in der Nachbedingung so, als wäre sie als _When_(expr, anno)codiert. Die _Success_ Anmerkung kann nur für eine Funktion verwendet werden, nicht für deren Parameter oder Rückgabetyp. Es kann höchstens eine _Success_ Anmerkung für eine Funktion vorhanden sein, und sie darf nicht in , _At__When_oder _Group_enthalten sein. Weitere Informationen finden Sie unter Angeben, wann und wo eine Anmerkung angewendet wird.

Siehe auch