From 16aba12a84575175f220d8844c5ecb4c88a341fe 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 1ca13c811..5c051852e 100644
--- a/src/db/db/gsiDeclDbCell.cc
+++ b/src/db/db/gsiDeclDbCell.cc
@@ -1491,6 +1491,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."
   ) + 
@@ -3453,6 +3454,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 79574277b..2e85264b4 100644
--- a/src/db/db/gsiDeclDbLayout.cc
+++ b/src/db/db/gsiDeclDbLayout.cc
@@ -1028,11 +1028,12 @@ Class<db::Layout> decl_Layout ("db", "Layout",
     "This method has been introduced in version 0.24."
   ) + 
   gsi::method_ext ("set_property", &set_layout_property, gsi::arg ("key"), gsi::arg ("value"),
-    "@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"
     "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 b0ae59e3b..1062c1374 100644
--- a/src/db/db/gsiDeclDbShape.cc
+++ b/src/db/db/gsiDeclDbShape.cc
@@ -1283,6 +1283,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"/>