From a452853c45988d69416788382931d52acff54b0c Mon Sep 17 00:00:00 2001
From: Thomas Ferreira de Lima <tlima@princeton.edu>
Date: Wed, 11 Nov 2020 22:33:51 -0500
Subject: [PATCH] Adding clarification on GDS properties in cell, instance,
 shape and layout.

---
 src/db/db/gsiDeclDbCell.cc                   | 2 ++
 src/db/db/gsiDeclDbLayout.cc                 | 3 ++-
 src/db/db/gsiDeclDbShape.cc                  | 1 +
 src/lay/lay/doc/programming/database_api.xml | 7 +++++++
 4 files changed, 12 insertions(+), 1 deletion(-)

diff --git a/src/db/db/gsiDeclDbCell.cc b/src/db/db/gsiDeclDbCell.cc
index 675c27fb4..8bf86bc53 100644
--- a/src/db/db/gsiDeclDbCell.cc
+++ b/src/db/db/gsiDeclDbCell.cc
@@ -1809,6 +1809,7 @@ Class<db::Cell> decl_Cell ("db", "Cell",
     "If no property with that key exists, it will create one. Using that method is more "
     "convenient than creating a new property set with a new ID and assigning that properties ID.\n"
     "This method may change the properties ID. "
+    "Note: GDS only supports integer keys. OASIS supports numeric and string keys. "
     "\n"
     "This method has been introduced in version 0.23."
   ) + 
@@ -3821,6 +3822,7 @@ Class<db::Instance> decl_Instance ("db", "Instance",
     "If no property with that key exists, it will create one. Using that method is more "
     "convenient than creating a new property set with a new ID and assigning that properties ID.\n"
     "This method may change the properties ID. "
+    "Note: GDS only supports integer keys. OASIS supports numeric and string keys. "
     "Calling this method may invalidate any iterators. It should not be called inside a "
     "loop iterating over instances.\n"
     "\n"
diff --git a/src/db/db/gsiDeclDbLayout.cc b/src/db/db/gsiDeclDbLayout.cc
index 12ebf1cd2..7abbd7a9b 100644
--- a/src/db/db/gsiDeclDbLayout.cc
+++ b/src/db/db/gsiDeclDbLayout.cc
@@ -1038,12 +1038,13 @@ Class<db::Layout> decl_Layout ("db", "Layout",
     "This method has been introduced in version 0.24."
   ) + 
   gsi::method_ext ("set_property", &set_layout_property,
-    "@brief Set the user property with the given key to the given value\n"
+    "@brief Sets the user property with the given key to the given value\n"
     "@args key, value\n"
     "This method is a convenience method that sets the property with the given key to the given value. "
     "If no property with that key exists, it will create one. Using that method is more "
     "convenient than creating a new property set with a new ID and assigning that properties ID.\n"
     "This method may change the properties ID. "
+    "Note: GDS only supports integer keys. OASIS supports numeric and string keys. "
     "\n"
     "This method has been introduced in version 0.24."
   ) + 
diff --git a/src/db/db/gsiDeclDbShape.cc b/src/db/db/gsiDeclDbShape.cc
index 276908fd9..e6f818a15 100644
--- a/src/db/db/gsiDeclDbShape.cc
+++ b/src/db/db/gsiDeclDbShape.cc
@@ -1292,6 +1292,7 @@ Class<db::Shape> decl_Shape ("db", "Shape",
     "If no property with that key exists, it will create one. Using that method is more "
     "convenient than creating a new property set with a new ID and assigning that properties ID.\n"
     "This method may change the properties ID. "
+    "Note: GDS only supports integer keys. OASIS supports numeric and string keys. "
     "Calling this method will invalidate any iterators. It should not be called inside a "
     "loop iterating over shapes.\n"
     "\n"
diff --git a/src/lay/lay/doc/programming/database_api.xml b/src/lay/lay/doc/programming/database_api.xml
index 152ac2bff..07fe4b06a 100644
--- a/src/lay/lay/doc/programming/database_api.xml
+++ b/src/lay/lay/doc/programming/database_api.xml
@@ -473,6 +473,13 @@ shape.set_property(1, "NewValue")</pre>
   and "delete_property" also are provided for cells and cell instances (<class_doc href="Cell"/> and <class_doc href="Instance"/>).
   </p>
 
+  <p>
+  <b>Note:</b> The GDS format does not have string names for properties. As a result GDS only supports numeric property keys.
+  OASIS, on the other hand, can handle string and numeric property "names". When saving layouts in GDS format, KLayout tries
+  to convert the properties' names into numbers if possible (i.e. if it sees that the string is a number). If it can't, then
+  the property is not saved. When the layout is read by KLayout upon opening, it gets converted to integer.
+  </p>
+
   <h2>The LayerInfo class</h2>
 
   <keyword name="LayerInfo"/>