Merge pull request #1907 from svaarala/api-doc-note-vararg-limitations

Document vararg API call portability limitation for va_end()

website/api/duk_error_va.yaml

@@ -10,6 +10,8 @@ summary: |
   <p>Vararg variant of
   <code><a href="#duk_error">duk_error()</a></code>.</p>
 
+  <div include="vararg-portability.html" />
+
 example: |
   void my_range_error(duk_context *ctx, const char *fmt, ...) {
       va_list ap;

website/api/duk_eval_error_va.yaml

@@ -11,6 +11,8 @@ summary: |
   <code><a href="#duk_error_va">duk_error_va()</a></code> with an error code
   <code>DUK_ERR_EVAL_ERROR</code>.</p>
 
+  <div include="vararg-portability.html" />
+
 example: |
   void my_eval_error(duk_context *ctx, const char *fmt, ...) {
       va_list ap;

website/api/duk_generic_error_va.yaml

@@ -11,6 +11,8 @@ summary: |
   <code><a href="#duk_error_va">duk_error_va()</a></code> with an error code
   <code>DUK_ERR_ERROR</code>.</p>
 
+  <div include="vararg-portability.html" />
+
 example: |
   void my_generic_error(duk_context *ctx, const char *fmt, ...) {
       va_list ap;

website/api/duk_push_error_object_va.yaml

@@ -10,6 +10,8 @@ summary: |
   <p>Vararg variant of
   <code><a href="#duk_push_error_object">duk_push_error_object()</a></code>.</p>
 
+  <div include="vararg-portability.html" />
+
 example: |
   duk_idx_t my_type_error(duk_context *ctx, const char *fmt, ...) {
       va_list ap;

website/api/duk_push_vsprintf.yaml

@@ -26,6 +26,8 @@ summary: |
   This is a limitation of the vararg mechanism.</p>
   </div>
 
+  <div include="vararg-portability.html" />
+
 example: |
   void test_vsprintf(duk_context *ctx, ...) {
       va_list ap;

website/api/duk_range_error_va.yaml

@@ -11,6 +11,8 @@ summary: |
   <code><a href="#duk_error_va">duk_error_va()</a></code> with an error code
   <code>DUK_ERR_RANGE_ERROR</code>.</p>
 
+  <div include="vararg-portability.html" />
+
 example: |
   void my_range_error(duk_context *ctx, const char *fmt, ...) {
       va_list ap;

website/api/duk_reference_error_va.yaml

@@ -11,6 +11,8 @@ summary: |
   <code><a href="#duk_error_va">duk_error_va()</a></code> with an error code
   <code>DUK_ERR_REFERENCE_ERROR</code>.</p>
 
+  <div include="vararg-portability.html" />
+
 example: |
   void my_reference_error(duk_context *ctx, const char *fmt, ...) {
       va_list ap;

website/api/duk_syntax_error_va.yaml

@@ -11,6 +11,8 @@ summary: |
   <code><a href="#duk_error_va">duk_error_va()</a></code> with an error code
   <code>DUK_ERR_SYNTAX_ERROR</code>.</p>
 
+  <div include="vararg-portability.html" />
+
 example: |
   void my_syntax_error(duk_context *ctx, const char *fmt, ...) {
       va_list ap;

website/api/duk_type_error_va.yaml

@@ -11,6 +11,8 @@ summary: |
   <code><a href="#duk_error_va">duk_error_va()</a></code> with an error code
   <code>DUK_ERR_TYPE_ERROR</code>.</p>
 
+  <div include="vararg-portability.html" />
+
 example: |
   void my_type_error(duk_context *ctx, const char *fmt, ...) {
       va_list ap;

website/api/duk_uri_error_va.yaml

@@ -11,6 +11,8 @@ summary: |
   <code><a href="#duk_error_va">duk_error_va()</a></code> with an error code
   <code>DUK_ERR_URI_ERROR</code>.</p>
 
+  <div include="vararg-portability.html" />
+
 example: |
   void my_uri_error(duk_context *ctx, const char *fmt, ...) {
       va_list ap;

website/api/vararg-portability.html

@@ -0,0 +1,9 @@
+<div>
+<div class="note">
+This API call is not fully portable because the va_end() macro in the calling
+code may never be reached (e.g. due to an error throw).  Some implementations
+rely on va_end() to e.g. free memory allocated by va_start(); see
+<a href="https://stackoverflow.com/questions/11645282/do-i-need-to-va-end-when-an-exception-is-thrown">https://stackoverflow.com/questions/11645282/do-i-need-to-va-end-when-an-exception-is-thrown</a>.
+However, such implementations are rare so this isn't usually a practical concern.
+</div>
+</div>