Dela via

Kommentera funktionsbeteende

Förutom att kommentera funktionsparametrar och returvärden kan du kommentera egenskaper för hela funktionen.

Funktionsanteckningar

Följande anteckningar gäller för funktionen som helhet och beskriver hur den beter sig eller vad den förväntar sig vara sant.

Anteckning Beskrivning
_Called_from_function_class_(name) Inte avsedd att stå ensam; I stället är det ett predikat som ska användas med anteckningen _When_ . Mer information finns i Ange när och var en anteckning gäller.

Parametern name är en godtycklig sträng som också visas i en _Function_class_ kommentar i deklarationen av vissa funktioner. _Called_from_function_class_ returnerar ett icke-nollvärde om funktionen som för närvarande analyseras är annoterad med _Function_class_ som har samma värde som name; annars returneras noll.
_Check_return_ Kommenterar ett returvärde och anger att anroparen ska inspektera det. Kontrollen rapporterar ett fel om funktionen anropas i en void-kontext.
_Function_class_(name) Parametern name är en godtycklig sträng som användaren har angett. Den finns i ett namnområde som skiljer sig från andra namnområden. En funktion, funktionspekare eller – mest användbart – en funktionspekartyp kan betecknas som tillhör en eller flera funktionsklasser.
_Raises_SEH_exception_ Kommenterar en funktion som alltid genererar ett SEH-undantag (Structured Exception Handler), med förbehåll för _When_ och _On_failure_ villkor. Mer information finns i Ange när och var en anteckning gäller.
_Maybe_raises_SEH_exception_ Annoterar en funktion som kan generera ett SEH-undantag, beroende på _When_ och _On_failure_ villkor.
_Must_inspect_result_ Kommenterar alla utdatavärden, inklusive returvärdet, parametrarna och globalerna. Analysatorn rapporterar ett fel om värdet i det kommenterade objektet inte inspekteras senare. "Inspektion" omfattar om den används i ett villkorsuttryck, tilldelas till en utdataparameter eller en global variabel, eller skickas som en parameter. För returvärden medför _Must_inspect_result__Check_return_.
_Use_decl_annotations_ Kan användas i en funktionsdefinition (kallas även för en funktionstext) i stället för listan över anteckningar i rubriken. När _Use_decl_annotations_ används, behandlas de kommentarer som visas i ett omfattningshuvud för samma funktion som om de också finns i definitionen som har kommentaren _Use_decl_annotations_.

Kommentarer om framgång/misslyckande

En funktion kan misslyckas, och när den gör det kan dess resultat vara ofullständiga eller skilja sig från resultaten när funktionen lyckas. Anteckningarna i följande lista innehåller sätt att uttrycka felbeteendet. Om du vill använda de här anteckningarna måste du göra det möjligt för dem att avgöra om de lyckas. Därför krävs en _Success_ anteckning. Observera att NTSTATUS och HRESULT redan har en _Success_ inbyggd anteckning, men om du anger din egen _Success_ anteckning på NTSTATUS eller HRESULTåsidosätter den den inbyggda anteckningen.

Anteckning Beskrivning
_Always_(anno_list) anno_list _On_failure_(anno_list)Motsvarande , dvs. anteckningarna i anno_list gäller om funktionen lyckas eller inte.
_On_failure_(anno_list) Ska endast användas när _Success_ också används för att annotera funktionen – antingen explicit eller implicit genom _Return_type_success_ på en typedef. När anteckningen _On_failure_ finns på en funktionsparameter eller ett returvärde beter sig varje anteckning i anno_list (anno) som om den kodades som _When_(!expr, anno), där expr är parametern till den anteckning som krävs _Success_ . Det innebär att den underförstådda tillämpningen av _Success_ för alla eftervillkor inte gäller för _On_failure_.
_Return_type_success_(expr) Kan tillämpas på en typedef. Anger att alla funktioner som returnerar den typen och inte uttryckligen har _Success_ kommenteras som om de hade _Success_(expr). _Return_type_success_ kan inte användas på en funktion eller en funktionspekare typedef.
_Success_(expr) expr är ett uttryck som ger ett rvalue. När anteckningen _Success_ finns i en funktionsdeklaration eller definition beter sig varje anteckning (anno) på funktionen och i eftervillkor som om den kodades som _When_(expr, anno). Anteckningen _Success_ får endast användas på en funktion, inte på dess parametrar eller returtyp. Det kan finnas högst en _Success_ anteckning på en funktion, och den kan inte finnas i någon _When_, _At_eller _Group_. Mer information finns i Ange när och var en anteckning gäller.

Se även

  • Last updated on