From d7a41b860dff625c06e65b7a90178fd5738f7944 Mon Sep 17 00:00:00 2001
From: Matthias Koefferlein <matthias@klayout.de>
Date: Thu, 6 Aug 2026 21:26:18 +0200
Subject: [PATCH] Clarify layer parameters in doc.

---
 src/doc/doc/programming/ruby_pcells.xml | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/src/doc/doc/programming/ruby_pcells.xml b/src/doc/doc/programming/ruby_pcells.xml
index d068d3ef5..d407ff4e6 100644
--- a/src/doc/doc/programming/ruby_pcells.xml
+++ b/src/doc/doc/programming/ruby_pcells.xml
@@ -288,12 +288,21 @@ end</pre>
   </p>
 
   <ul>
-    <li><tt>l, set_l, l_layer</tt>: getter and setter for the current value of "l". l_layer is the layer index in the context 
+    <li><tt>l, set_l, l_layer</tt>: getter and setter for the current value of "l". "l_layer" is the layer index in the context 
       of the PCell production method. The layer index can be used to access the layer in the layout or cell.</li>
     <li><tt>s, set_s</tt>: getter and setter for the current value of "s".</li>
     <li><tt>r, set_r, n, set_n, ru, set_ru</tt>: same for "r", "n" and "ru".</li>
   </ul>  
 
+  <p>
+  Layer parameters are "optional" is a sense that the value can always be set to "empty" by the user. 
+  "Empty" layers have a <class_doc href="LayerInfo"/> value that is "anonymous". In general it
+  is a good idea to check production code for an anonymous layer info and skip shape generation
+  in that case. Empty layers can be present if a PCell is freshly initialized or the layer is 
+  not yet given by the user. A PCell should behave nicely in that case and not empty any polygons
+  to a non-existing layer. 
+  </p>
+
   <p>
   After the PCell initialization is finished, we can start with the production code. These are the methods
   that KLayout will call on certain opportunities. The first method that a PCell must implement is the