From 03f0dd20257e56bbb1b673cecb05fbf8760497a8 Mon Sep 17 00:00:00 2001
From: Sami Vaarala <sami.vaarala@iki.fi>
Date: Fri, 10 Oct 2014 14:02:55 +0300
Subject: [PATCH] Update guide on internal property naming

---
 website/guide/internalproperties.html | 47 +++++++++++++++------------
 1 file changed, 26 insertions(+), 21 deletions(-)

diff --git a/website/guide/internalproperties.html b/website/guide/internalproperties.html
index d4134ca6..db9e5931 100644
--- a/website/guide/internalproperties.html
+++ b/website/guide/internalproperties.html
@@ -21,16 +21,15 @@ property names and ordinary Ecmascript code cannot accidentally access them.</p>
 reference, for storing the underlying primitive value for various objects
 (such as <code>Date</code> and <code>Number</code>) and for storing control
 properties of function instances.  The current naming convention of
-Duktape's internal properties is to follow the <code>0xFF</code> with
-an identifier matching <code>[a-z0-9_]+</code> (no uppercase characters).
-For instance, the underlying timestamp of a <code>Date</code> is (currently)
-stored as the internal property <code>\xFFvalue</code> (byte sequence
-<code>ff 76 61 6c 75 65</code>).
-Note that this is different from the valid Ecmascript string <code>"\u00ffvalue"</code>
+Duktape's internal properties is to follow the <code>0xFF</code> with one
+uppercase character, which is followed by <code>[a-z0-9_]*</code>.  For instance,
+the underlying timestamp of a <code>Date</code> is (currently) stored as the
+internal property <code>\xFFValue</code> (byte sequence <code>ff 56 61 6c 75 65</code>).
+Note that this is different from the valid Ecmascript string <code>"\u00ffValue"</code>
 which Duktape would represent internally as the CESU-8 byte sequence
-<code>c3 bf 76 61 6c 75 65</code>.  The initial byte is often represented by
-an underscore in documentation for readability, e.g. <code>_value</code> is used
-instead of <code>\xFFvalue</code>.</p>
+<code>c3 bf 56 61 6c 75 65</code>.  The initial byte is often represented by
+an underscore in documentation for readability, e.g. <code>_Value</code> is used
+instead of <code>\xFFValue</code>.</p>
 
 <div class="note">
 User code should never try to access Duktape's internal properties.  The set
@@ -39,13 +38,19 @@ of internal properties used can change arbitrarily between versions.
 
 <p>User code can also use internal properties for its own purposes, e.g. to
 store "hidden state" in objects, as long as the property names never
-conflict with current or future Duktape internal property names.
-The recommended approach for now is to prefix user internal properties with
-two <code>0xFF</code> bytes, e.g. <code>\xFF\xFFmyprop</code> (byte sequence
-<code>ff ff 6d 79 70 72 6f 70</code>).  (Note, again, that this is different
-from the valid Ecmascript string <code>"\u00ff\u00ffmyprop"</code> which would
-be represented as the CESU-8 byte sequence
-<code>c3 bf c3 bf 6d 79 70 72 6f 70</code>.)</p>
+conflict with current or future Duktape internal property names.  Because
+Duktape internal keys always begin with a capital letter, the recommended
+approach is to begin user internal key names with a lowercase character in
+the normal Ecmascript convention, e.g. <code>\xFFmyprop</code> (byte sequence
+<code>ff 6d 79 70 72 6f 70</code>)
+(Note, again, that this is different from the valid Ecmascript string
+<code>"\u00ffmyprop"</code> which would be represented as the CESU-8 byte
+sequence <code>c3 bf 6d 79 70 72 6f 70</code>.)</p>
+
+<p>If the user internal key is not known in advance (perhaps it's generated
+by serializing a pointer or something similar), you can simply use two
+ <code>0xFF</code> prefix bytes, followed by arbitrary string data, e.g.
+<code>\xFF\xFF&lt;arbitrary string&gt;</code>.</p>
 
 <p>Creating an internal string is easy from C code:</p>
 <pre class="c-code">
@@ -54,7 +59,7 @@ be represented as the CESU-8 byte sequence
  * Terminating a string literal after a hex escape is safest to avoid some
  * ambiguous cases like "\xffab".
  */
-duk_push_string(ctx, "\xff\xff" "myprop");
+duk_push_string(ctx, "\xff" "myprop");
 </pre>
 
 <p>For more discussion on C string hex escaping, see
@@ -65,12 +70,12 @@ to e.g. the Buffer constructor or <code>Duktape.dec()</code> (this must be consi
 in sandboxing):</p>
 <pre class="ecmascript-code">
 // Using Duktape.Buffer()
-var buf = new Duktape.Buffer(2);
-buf[0] = 255; buf[1] = 255;
+var buf = new Duktape.Buffer(1);
+buf[0] = 255;
 var key1 = buf + 'myprop';
 
 // Using Duktape.dec()
-var key2 = Duktape.dec('hex', 'ffff6d7970726f70');  // \xFF\xFFmyprop
+var key2 = Duktape.dec('hex', 'ff6d7970726f70');  // \xFFmyprop
 </pre>
 
 <p>There's no special access control for internal properties: if user code has
@@ -89,7 +94,7 @@ accessed as follows:</p>
 // actually do this because the internal properties may change between
 // versions in an arbitrary manner!
 
-var key = Duktape.dec('hex', 'ff76616c7565');  // \xFFvalue
+var key = Duktape.dec('hex', 'ff56616c7565');  // \xFFValue
 var dt = new Date(123456);
 print('internal value is:', dt[key]);  // prints 123456
 </pre>