From 8eb3205aabb986ff26757cd54667e293f5094316 Mon Sep 17 00:00:00 2001
From: apenn-msft <62863214+apenn-msft@users.noreply.github.com>
Date: Mon, 3 Feb 2025 17:24:20 -0500
Subject: [PATCH] explicitly document finally actions must be non-throwing

because the gsl::final_action destructor is marked noexcept(true), the action cannot throw else the program will terminate; this nuance should be documented explicitly and (to be investigated later) ideally enforced in code.
---
 docs/headers.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/headers.md b/docs/headers.md
index 96465a3..5d92d32 100644
--- a/docs/headers.md
+++ b/docs/headers.md
@@ -794,7 +794,7 @@ template <class F>
 class final_action { ... };
 ```
 
-`final_action` allows you to ensure something gets run at the end of a scope.
+`final_action` allows you to ensure non-throwing code is executed at the end of a scope.
 
 See [E.19: Use a final_action object to express cleanup if no suitable resource handle is available](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Re-finally)
 
@@ -805,13 +805,13 @@ explicit final_action(const F& ff) noexcept;
 explicit final_action(F&& ff) noexcept;
 ```
 
-Construct an object with the action to invoke in the destructor.
+Construct an object with the non-throwing action to invoke in the destructor.
 
 ```cpp
 ~final_action() noexcept;
 ```
 
-The destructor will call the action that was passed in the constructor.
+The destructor will invoke the action that was passed in the constructor; if the action throws an exception the program will terminate.
 
 ```cpp
 final_action(final_action&& other) noexcept;