doc/ref: propose reserving identifiiers starting with `__`

Change-Id: I9e70fd765de6f448dbc0fa2cd1f3e78024151fd2
Reviewed-by: Marcel van Lohuizen <>
diff --git a/doc/ref/ b/doc/ref/
index f68abd5..7ec05ba 100644
--- a/doc/ref/
+++ b/doc/ref/
@@ -1273,6 +1273,17 @@
 exception of identifiers starting with an underscore '_'.
 The latter represent hidden fields and are treated in a different namespace.
+<!-- TODO: disallow creating identifiers starting with __
+...and reserve them for builtin values.
+The issue is with code generation. As no guarantee can be given that
+a predeclared identifier is not overridden in one of the enclosing scopes,
+code will have to handle detecting such cases and renaming them.
+An alternative is to have the predeclared identifiers be aliases for namesake
+equivalents starting with a double underscore (e.g. string -> __string),
+allowing generated code (normal code would keep using `string`) to refer
+to these directly.
 ### Alias declarations