From 01b4ace41e02c196fe390bc3ae1acd70cfa2163d Mon Sep 17 00:00:00 2001
From: Sami Vaarala <sami.vaarala@iki.fi>
Date: Sun, 15 May 2016 04:37:40 +0300
Subject: [PATCH] API doc updates for panic removal

---
 website/api/defines.html         |  2 +-
 website/api/duk_create_heap.yaml | 17 ++++++++++-------
 website/api/duk_fatal.yaml       | 10 +++++-----
 3 files changed, 16 insertions(+), 13 deletions(-)

diff --git a/website/api/defines.html b/website/api/defines.html
index f3d33214..8389d159 100644
--- a/website/api/defines.html
+++ b/website/api/defines.html
@@ -52,7 +52,7 @@ typedef duk_ret_t (*duk_c_function)(duk_context *ctx);
 typedef void *(*duk_alloc_function) (void *udata, duk_size_t size);
 typedef void *(*duk_realloc_function) (void *udata, void *ptr, duk_size_t size);
 typedef void (*duk_free_function) (void *udata, void *ptr);
-typedef void (*duk_fatal_function) (duk_context *ctx, duk_errcode_t code, const char *msg);
+typedef void (*duk_fatal_function) (void *udata, const char *msg);
 typedef void (*duk_decode_char_function) (void *udata, duk_codepoint_t codepoint);
 typedef duk_codepoint_t (*duk_map_char_function) (void *udata, duk_codepoint_t codepoint);
 typedef duk_ret_t (*duk_safe_call_function) (duk_context *ctx, void *udata);
diff --git a/website/api/duk_create_heap.yaml b/website/api/duk_create_heap.yaml
index 0a1bbc65..c427559c 100644
--- a/website/api/duk_create_heap.yaml
+++ b/website/api/duk_create_heap.yaml
@@ -19,16 +19,19 @@ summary: |
   memory management functions (ANSI C <code>malloc()</code>, <code>realloc()</code>
   , and <code>free()</code>) are used.  The memory management functions
   share the same opaque userdata pointer, <code>heap_udata</code>.  This
-  userdata pointer is also used for other Duktape features (like low memory
-  pointer compression macros).</p>
+  userdata pointer is also used for other Duktape features like fatal error
+  handling and low memory pointer compression macros.</p>
 
   <p>A fatal error handler is provided in <code>fatal_handler</code>.  This
   handler is called in unrecoverable error situations such as uncaught
-  errors, out-of-memory errors not resolved by garbage collection, etc.
-  A caller SHOULD implement a fatal error handler in most applications.
-  If not given, a default fatal error handler is used.  The default
-  handler ultimately calls ANSI C <code>abort()</code>, which may not always
-  be the preferred action.</p>
+  errors, out-of-memory errors not resolved by garbage collection, self test
+  errors, etc.  A caller SHOULD implement a fatal error handler in most
+  applications.  If not given, a default fatal error handler built into
+  Duktape is used instead.  <b>Note that the default fatal error handler (unless
+  overridden by <code>duk_config.h</code>) causes an intentional segfault to
+  exit a process to avoid relying on platform API calls like abort().</b>  See
+  <a href="http://wiki.duktape.org/HowtoFatalErrors.html">How to handle fatal errors</a>
+  for more detail and examples.</p>
 
   <p>To create a Duktape heap with default settings, use
   <code><a href="#duk_create_heap_default">duk_create_heap_default()</a></code>.</p>
diff --git a/website/api/duk_fatal.yaml b/website/api/duk_fatal.yaml
index 44f0a0f3..253754c0 100644
--- a/website/api/duk_fatal.yaml
+++ b/website/api/duk_fatal.yaml
@@ -1,12 +1,12 @@
 name: duk_fatal
 
 proto: |
-  void duk_fatal(duk_context *ctx, duk_errcode_t err_code, const char *err_msg);
+  void duk_fatal(duk_context *ctx, const char *err_msg);
 
 summary: |
-  <p>Call fatal error handler with a specified error code and an optional
-  message (<code>err_msg</code> may be <code>NULL</code>).  The valid range
-  for user error codes is [1,16777215].</p>
+  <p>Call fatal error handler with an optional message (<code>err_msg</code>
+  may be <code>NULL</code>).  Like all strings in Duktape, the error message
+  should be an UTF-8 string, although pure ASCII is strongly recommended.</p>
 
   <p>A fatal error handler never returns and may e.g. exit the current
   process.  Error catching points (like <code>try-catch</code> statements
@@ -15,7 +15,7 @@ summary: |
   has occurred.</p>
 
 example: |
-  duk_fatal(ctx, DUK_ERR_INTERNAL_ERROR, "assumption failed");
+  duk_fatal(ctx, "assumption failed");
 
 tags:
   - error