From a9c7257beaf8eeef25fddd3b8bf87b51de158f69 Mon Sep 17 00:00:00 2001
From: Sami Vaarala <sami.vaarala@iki.fi>
Date: Fri, 28 Oct 2016 21:23:22 +0300
Subject: [PATCH] API doc changes for duk_{throw,error,fatal}()

---
 website/api/duk_error.yaml    | 10 +++++++++-
 website/api/duk_error_va.yaml |  2 +-
 website/api/duk_fatal.yaml    |  9 ++++++++-
 website/api/duk_throw.yaml    | 11 ++++++++++-
 4 files changed, 28 insertions(+), 4 deletions(-)

diff --git a/website/api/duk_error.yaml b/website/api/duk_error.yaml
index bef2abbe..590393a7 100644
--- a/website/api/duk_error.yaml
+++ b/website/api/duk_error.yaml
@@ -1,7 +1,7 @@
 name: duk_error
 
 proto: |
-  void duk_error(duk_context *ctx, duk_errcode_t err_code, const char *fmt, ...);
+  duk_ret_t duk_error(duk_context *ctx, duk_errcode_t err_code, const char *fmt, ...);
 
 stack: |
   [ ... ] -> [ ... err! ]
@@ -20,6 +20,14 @@ summary: |
   <code><a href="#duk_push_error_object">duk_push_error_object()</a></code>.
   </p>
 
+  <p>Even though the function never returns, the prototype describes a return
+  value which allows code such as:</p>
+  <pre class="c-code">
+  if (argvalue &lt; 0) {
+      return duk_error(ctx, DUK_ERR_TYPE_ERROR, "invalid argument value: %d", (int) argvalue);
+  }
+  </pre>
+
 example: |
   duk_error(ctx, DUK_ERR_RANGE_ERROR, "argument out of range: %d", (int) argval);
 
diff --git a/website/api/duk_error_va.yaml b/website/api/duk_error_va.yaml
index 2bc51566..1b3aefe7 100644
--- a/website/api/duk_error_va.yaml
+++ b/website/api/duk_error_va.yaml
@@ -1,7 +1,7 @@
 name: duk_error_va
 
 proto: |
-  void duk_error_va(duk_context *ctx, duk_errcode_t err_code, const char *fmt, va_list ap);
+  duk_ret_t duk_error_va(duk_context *ctx, duk_errcode_t err_code, const char *fmt, va_list ap);
 
 stack: |
   [ ... ] -> [ ... err! ]
diff --git a/website/api/duk_fatal.yaml b/website/api/duk_fatal.yaml
index 253754c0..d147acf9 100644
--- a/website/api/duk_fatal.yaml
+++ b/website/api/duk_fatal.yaml
@@ -1,7 +1,7 @@
 name: duk_fatal
 
 proto: |
-  void duk_fatal(duk_context *ctx, const char *err_msg);
+  duk_ret_t duk_fatal(duk_context *ctx, const char *err_msg);
 
 summary: |
   <p>Call fatal error handler with an optional message (<code>err_msg</code>
@@ -14,6 +14,13 @@ summary: |
   You should only call this function when a truly fatal, unrecoverable error
   has occurred.</p>
 
+  <p>Even though the function never returns, the prototype describes a return
+  value which allows code such as:</p>
+  <pre class="c-code">
+  if (argvalue &lt; 0) {
+      return duk_fatal(ctx, "argvalue invalid, cannot continue execution");
+  }
+
 example: |
   duk_fatal(ctx, "assumption failed");
 
diff --git a/website/api/duk_throw.yaml b/website/api/duk_throw.yaml
index 9c546323..09c83e90 100644
--- a/website/api/duk_throw.yaml
+++ b/website/api/duk_throw.yaml
@@ -1,7 +1,7 @@
 name: duk_throw
 
 proto: |
-  void duk_throw(duk_context *ctx);
+  duk_ret_t duk_throw(duk_context *ctx);
 
 stack: |
   [ ... val! ]
@@ -9,6 +9,15 @@ stack: |
 summary: |
   <p>Throw the value on top of the stack.  This call never returns.</p>
 
+  <p>Even though the function never returns, the prototype describes a return
+  value which allows code such as:</p>
+  <pre class="c-code">
+  if (argvalue &lt; 0) {
+      duk_push_error_object(ctx, DUK_ERR_TYPE_ERROR, "invalid argument: %d", (int) argvalue);
+      return duk_throw(ctx);
+  }
+  </pre>
+
 example: |
   /* Throw a string value; equivalent to the Ecmascript code:
    *