From a20bd38f17c68a1bdb544dc5b2b79cfcf7522c19 Mon Sep 17 00:00:00 2001
From: Matthias Koefferlein <matthias@koefferlein.de>
Date: Tue, 15 Sep 2020 00:19:47 +0200
Subject: [PATCH] Updated documentation

---
 src/lay/lay/doc/about/drc_ref_global.xml | 45 +++++++++++++++++++++---
 src/lay/lay/doc/about/drc_ref_layer.xml  | 32 +++++++++++++++++
 2 files changed, 73 insertions(+), 4 deletions(-)

diff --git a/src/lay/lay/doc/about/drc_ref_global.xml b/src/lay/lay/doc/about/drc_ref_global.xml
index 5cf550238..76ed7823d 100644
--- a/src/lay/lay/doc/about/drc_ref_global.xml
+++ b/src/lay/lay/doc/about/drc_ref_global.xml
@@ -255,7 +255,7 @@ See <a href="/about/drc_ref_netter.xml#connect_implicit">Netter#connect_implicit
 <keyword name="dbu"/>
 <p>Usage:</p>
 <ul>
-<li><tt>dbu(dbu)</tt></li>
+<li><tt>dbu(dbu_value)</tt></li>
 <li><tt>dbu</tt></li>
 </ul>
 <p>
@@ -554,6 +554,39 @@ delivered by <a href="#polygon_layer">polygon_layer</a> is not.
 On the other hand, a layer created by the <a href="#make_layer">make_layer</a> method is not intended to be
 filled with <a href="/about/drc_ref_layer.xml#insert">Layer#insert</a>.
 </p>
+<a name="max_area_ratio"/><h2>"max_area_ratio" - Gets or sets the maximum bounding box to polygon area ratio for deep mode fragmentation</h2>
+<keyword name="max_area_ratio"/>
+<p>Usage:</p>
+<ul>
+<li><tt>max_area_ratio(ratio)</tt></li>
+<li><tt>max_area_ratio</tt></li>
+</ul>
+<p>
+In deep mode, polygons with a bounding box to polygon area ratio bigger than the given number
+will be split into smaller chunks to optimize performance (which gets better if the polygon's
+bounding boxes do not cover a lot of empty space).
+The default threshold is 3.0 which means fairly compact polygons. Use this method with a numeric 
+argument to set the value and without an argument to get the current maximum area ratio.
+Set the value to zero to disable splitting by area ratio.
+</p><p>
+See also <a href="#max_vertex_count">max_vertex_count</a> for the other option affecting polygon splitting.
+</p>
+<a name="max_vertex_count"/><h2>"max_vertex_count" - Gets or sets the maximum vertex count for deep mode fragmentation</h2>
+<keyword name="max_vertex_count"/>
+<p>Usage:</p>
+<ul>
+<li><tt>max_vertex_count(count)</tt></li>
+<li><tt>max_vertex_count</tt></li>
+</ul>
+<p>
+In deep mode, polygons with more than the given number of vertexes will be split into
+smaller chunks to optimize performance (which is better or less complex polygons).
+The default threshold is 16 vertexes. Use this method with a vertex count to set the
+value and without an argument to get the current maximum vertex count.
+Set the value to zero to disable splitting by vertex count.
+</p><p>
+See also <a href="#max_area_ratio">max_area_ratio</a> for the other option affecting polygon splitting.
+</p>
 <a name="mos3"/><h2>"mos3" - Supplies the MOS3 transistor extractor class</h2>
 <keyword name="mos3"/>
 <p>Usage:</p>
@@ -853,18 +886,22 @@ See <a href="#write_spice">write_spice</a> for more details.
 <p>Usage:</p>
 <ul>
 <li><tt>threads(n)</tt></li>
+<li><tt>threads</tt></li>
 </ul>
 <p>
 If using threads, tiles are distributed on multiple CPU cores for
 parallelization. Still, all tiles must be processed before the 
-operation proceeds with the next statement.
+operation proceeds with the next statement. 
+</p><p>
+Without an argument, "threads" will return the current number of 
+threads
 </p>
 <a name="tile_borders"/><h2>"tile_borders" - Specifies a minimum tile border</h2>
 <keyword name="tile_borders"/>
 <p>Usage:</p>
 <ul>
-<li><tt>tile_border(b)</tt></li>
-<li><tt>tile_border(bx, by)</tt></li>
+<li><tt>tile_borders(b)</tt></li>
+<li><tt>tile_borders(bx, by)</tt></li>
 </ul>
 <p>
 The tile border specifies the distance to which shapes are collected into the 
diff --git a/src/lay/lay/doc/about/drc_ref_layer.xml b/src/lay/lay/doc/about/drc_ref_layer.xml
index 439fb74bd..fe5f8f27c 100644
--- a/src/lay/lay/doc/about/drc_ref_layer.xml
+++ b/src/lay/lay/doc/about/drc_ref_layer.xml
@@ -627,6 +627,38 @@ If the layer is a hierarchical layer (an original layer or
 a derived layer in deep mode), this method will convert it
 to a flat collection of texts, polygons, edges or edge pairs.
 </p>
+<a name="forget"/><h2>"forget" - Cleans up memory for this layer</h2>
+<keyword name="forget"/>
+<p>Usage:</p>
+<ul>
+<li><tt>forget</tt></li>
+</ul>
+<p>
+KLayout's DRC engine is imperative. This means, every command is executed immediately
+rather than being compiled and executed later. The advantage of this approach is that
+it allows decisions to be taken depending on the content of a layer and to code 
+functions that operate directly on the layer's content.
+</p><p>
+However, one drawback is that the engine cannot decide when a layer is no longer 
+required - it may still be used later in the script. So a layer's data is not cleaned
+up automatically.
+</p><p>
+In order to save memory for DRC scripts intended for bigger layouts, the DRC script
+should clean up layers as soon as they are no longer required. The "forget" method
+will free the memory used for the layer's information.
+</p><p>
+The recommended approach is:
+</p><p>
+<pre>
+l = ... # compute some layer
+...
+# once you're done with l:
+l.forget
+l = nil
+</pre>
+</p><p>
+By setting the layer to nil, it is ensured that it can no longer be accessed.
+</p>
 <a name="holes"/><h2>"holes" - Selects all polygon holes from the input</h2>
 <keyword name="holes"/>
 <p>Usage:</p>