Fixed some documentation issues, DRC doc updated.

scripts/extract_doc.rb

@@ -72,6 +72,8 @@ class DocItem
       end
     end
 
+    self.name || raise("Doc block without name")
+
     para && @paragraphs.push(para)
 
   end
@@ -247,16 +249,25 @@ collector = Collector::new
 File.open($infile, "r") do |file|
 
   block = nil
+  line = 0
 
   file.each_line do |l|
-    l = unescape(l)
-    if l =~ /^\s*#\s*#{$key}/
-      block = []
-    elsif l =~ /^\s*#\s*(.*)\s*$/
-      block && block.push($1)
-    elsif l =~ /^\s*$/
-      block && collector.add_block(block)
-      block = nil
+
+    line += 1
+
+    begin
+      l = unescape(l)
+      if l =~ /^\s*#\s*#{$key}/
+        block = []
+      elsif l =~ /^\s*#\s*(.*)\s*$/
+        block && block.push($1)
+      elsif l =~ /^\s*$/
+        block && collector.add_block(block)
+        block = nil
+      end
+    rescue => ex
+      puts "ERROR in line #{line}:\n" + ex.to_s
+      exit 1
     end
 
   end

src/db/db/gsiDeclDbLayoutToNetlist.cc

@@ -420,7 +420,7 @@ Class<db::LayoutToNetlist> decl_dbLayoutToNetlist ("db", "LayoutToNetlist",
     "@brief Reads the extracted netlist from the file.\n"
     "This method employs the native format of KLayout.\n"
   ) +
-  gsi::method_ext ("antenna_check", &antenna_check, gsi::arg ("gate"), gsi::arg ("metal"), gsi::arg ("ratio"), gsi::arg ("diodes", std::vector<tl::Variant> ()),
+  gsi::method_ext ("antenna_check", &antenna_check, gsi::arg ("gate"), gsi::arg ("metal"), gsi::arg ("ratio"), gsi::arg ("diodes", std::vector<tl::Variant> (), "[]"),
    "@brief Runs an antenna check on the extracted clusters\n"
    "\n"
    "The antenna check will traverse all clusters and run an antenna check\n"
@@ -437,7 +437,7 @@ Class<db::LayoutToNetlist> decl_dbLayoutToNetlist ("db", "LayoutToNetlist",
    "l2n.extract_netlist\n"
    "# check for antenna ratio 10.0 of metal vs. poly:\n"
    "errors = l2n.antenna(poly, metal, 10.0)\n"
-   "@endcode\n"
+   "@/code\n"
    "\n"
    "You can include diodes which rectify the antenna effect. "
    "Provide recognition layers for theses diodes and include them "
@@ -449,7 +449,7 @@ Class<db::LayoutToNetlist> decl_dbLayoutToNetlist ("db", "LayoutToNetlist",
    "errors = l2n.antenna(poly, metal, 10.0, [ diode_layer1 ])\n"
    "# include diode_layer1 and diode_layer2:"
    "errors = l2n.antenna(poly, metal, 10.0, [ diode_layer1, diode_layer2 ])\n"
-   "@endcode\n"
+   "@/code\n"
    "\n"
    "Diodes can be configured to partially reduce the antenna effect depending "
    "on their area. This will make the diode_layer1 increase the ratio by 50.0 "
@@ -459,7 +459,7 @@ Class<db::LayoutToNetlist> decl_dbLayoutToNetlist ("db", "LayoutToNetlist",
    "...\n"
    "# diode_layer1 increases the ratio by 50 per sqaure micrometer area:\n"
    "errors = l2n.antenna(poly, metal, 10.0 [ [ diode_layer, 50.0 ] ])\n"
-   "@endcode\n"
+   "@/code\n"
   ),
   "@brief A generic framework for extracting netlists from layouts\n"
   "\n"
@@ -496,11 +496,16 @@ Class<db::LayoutToNetlist> decl_dbLayoutToNetlist ("db", "LayoutToNetlist",
   "    The produced netlist is available with \\netlist. The Shapes of a\n"
   "    specific net are available with \\shapes_of_net. \\probe_net allows\n"
   "    finding a net by probing a specific location.\n"
-  "@li\n"
+  "@/li\n"
+  "@/ul\n"
   "\n"
-  "Another use model is using the extractor with an existing \\DeepShapeStore object "
-  "or even flat data. In this case, the preparation step is importing by "
-  "taking existing region data using the \\register method.\n"
+  "You can also use the extractor with an existing \\DeepShapeStore object "
+  "or even flat data. In this case, preparation means importing existing regions "
+  "with the \\register method.\n"
+  "If you want to use the \\LayoutToNetlist object with flat data, use the "
+  "'LayoutToNetlist(topcell, dbu)' constructor. If you want to use it with "
+  "hierarchical data and an existing DeepShapeStore object, use the "
+  "'LayoutToNetlist(dss)' constructor.\n"
   "\n"
   "This class has been introduced in version 0.26."
 );

src/drc/drc/built-in-macros/drc.lym

@@ -3596,7 +3596,6 @@ CODE
   # The netter object
 
   # %DRC%
-
   # @scope 
   # @name Netter 
   # @brief DRC Reference: Netter object
@@ -3608,7 +3607,7 @@ CODE
   #
   # An individual netter object can be created, if the netter results
   # need to be kept for multiple extractions. If you really need
-  # a Netter object, use the global \\netter function:
+  # a Netter object, use the global \netter function:
   #
   # @code
   # # create a new Netter object:
@@ -3649,7 +3648,12 @@ CODE
   # 
   # # this will remove all connections made
   # clear_connections
+  # ...
   # @/code
+  #
+  # Further functionality of the Netter object:
+  #
+  # More methods will be added in the future to support network-related features.
 
   class DRCNetter
 

src/lay/lay/doc/about/drc_ref.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE language SYSTEM "klayout_doc.dtd">
 
-<!-- generated by /home/matthias/klayout/master/scripts/extract_doc.rb  -->
+<!-- generated by /home/matthias/klayout/dvb/scripts/extract_doc.rb  -->
 <!-- DO NOT EDIT! -->
 
 <doc>
@@ -9,6 +9,7 @@
 <keyword name="DRC Reference"/>
 <topics>
 <topic href="/about/drc_ref_layer.xml"/>
+<topic href="/about/drc_ref_netter.xml"/>
 <topic href="/about/drc_ref_source.xml"/>
 <topic href="/about/drc_ref_global.xml"/>
 </topics>

src/lay/lay/doc/about/drc_ref_global.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE language SYSTEM "klayout_doc.dtd">
 
-<!-- generated by /home/matthias/klayout/master/scripts/extract_doc.rb  -->
+<!-- generated by /home/matthias/klayout/dvb/scripts/extract_doc.rb  -->
 <!-- DO NOT EDIT! -->
 
 <doc>
@@ -13,6 +13,15 @@ Most of them are convenience functions that basically act on some default object
 or provide function-like alternatives for the methods.
 </p>
 <h2-index/>
+<h2>"antenna_check" - Performs an antenna check</h2>
+<keyword name="antenna_check"/>
+<a name="antenna_check"/><p>Usage:</p>
+<ul>
+<li><tt>antenna_check(gate, metal, ratio, [ diode_specs ... ])</tt></li>
+</ul>
+<p>
+See <a href="/about/drc_ref_netter.xml#antenna_check">Netter#antenna_check</a> for a description of that function
+</p>
 <h2>"box" - Creates a box object</h2>
 <keyword name="box"/>
 <a name="box"/><p>Usage:</p>
@@ -42,6 +51,15 @@ cell("MACRO")
 l1 = input(1, 0)
 </pre>
 </p>
+<h2>"clear_connections" - Clears all connections stored so far</h2>
+<keyword name="clear_connections"/>
+<a name="clear_connections"/><p>Usage:</p>
+<ul>
+<li><tt>clear_connections</tt></li>
+</ul>
+<p>
+See <a href="/about/drc_ref_netter.xml#clear_connections">Netter#clear_connections</a> for a description of that function
+</p>
 <h2>"clip" - Specifies clipped input on the default source</h2>
 <keyword name="clip"/>
 <a name="clip"/><p>Usage:</p>
@@ -60,6 +78,15 @@ clip(0.mm, 0.mm, 0.5.mm, 0.6.mm)
 l1 = input(1, 0)
 </pre>
 </p>
+<h2>"connect" - Specifies a connection between two layers</h2>
+<keyword name="connect"/>
+<a name="connect"/><p>Usage:</p>
+<ul>
+<li><tt>connect(a, b)</tt></li>
+</ul>
+<p>
+See <a href="/about/drc_ref_netter.xml#connect">Netter#connect</a> for a description of that function.
+</p>
 <h2>"dbu" - Gets or sets the database unit to use</h2>
 <keyword name="dbu"/>
 <a name="dbu"/><p>Usage:</p>
@@ -79,6 +106,26 @@ for two layouts (i.e. take the largest common denominator).
 When the database unit is set, it must be set at the beginning
 of the script and before any operation that uses it.
 </p>
+<h2>"deep" - Enters deep (hierarchical) mode</h2>
+<keyword name="deep"/>
+<a name="deep"/><p>Usage:</p>
+<ul>
+<li><tt>deep</tt></li>
+</ul>
+<p>
+In deep mode, the operations will be performed in a hierarchical fashion. 
+Sometimes this reduces the time and memory required for an operation, but this
+will also add some overhead for the hierarchical analysis.
+</p><p>
+"deepness" is a property of layers. Layers created with "input" while in 
+deep mode carry hierarchy. Operations involving such layers at the only
+or the first argument are carried out in hierarchical mode. 
+</p><p>
+Hierarchical mode has some more implications, like "merged_semantics" being
+implied always. Sometimes cell variants will be created.
+</p><p>
+Deep mode can be cancelled with <a href="#tiles">tiles</a> or <a href="#flat">flat</a>.
+</p>
 <h2>"edge" - Creates an edge object</h2>
 <keyword name="edge"/>
 <a name="edge"/><p>Usage:</p>
@@ -146,6 +193,12 @@ In non-verbose more, nothing is printed.
 <p>
 See <a href="/about/drc_ref_source.xml#input">Source#input</a> for a description of that function.
 </p>
+<h2>"is_deep?" - Returns true, if in deep mode</h2>
+<keyword name="is_deep?"/>
+<a name="is_deep?"/><p>Usage:</p>
+<ul>
+<li><tt>is_deep?</tt></li>
+</ul>
 <h2>"is_tiled?" - Returns true, if in tiled mode</h2>
 <keyword name="is_tiled?"/>
 <a name="is_tiled?"/><p>Usage:</p>
@@ -228,6 +281,15 @@ verbose mode is enabled.
 After using that method, the log output is sent to the 
 given file instead of the logger window or the terminal.
 </p>
+<h2>"netter" - Creates a new netter object</h2>
+<keyword name="netter"/>
+<a name="netter"/><p>Usage:</p>
+<ul>
+<li><tt>netter</tt></li>
+</ul>
+<p>
+See <a href="#Netter">Netter</a> for more details
+</p>
 <h2>"no_borders" - Reset the tile borders</h2>
 <keyword name="no_borders"/>
 <a name="no_borders"/><p>Usage:</p>
@@ -459,7 +521,9 @@ predict.
 </p><p>
 In tiling mode, the memory requirements are usually smaller (depending on the 
 choice of the tile size) and multi-CPU support is enabled (see <a href="#threads">threads</a>).
-To disable tiling mode use <a href="#flat">flat</a>. 
+To disable tiling mode use <a href="#flat">flat</a> or <a href="#deep">deep</a>. 
+</p><p>
+Tiling mode will disable deep mode (see <a href="#deep">deep</a>).
 </p>
 <h2>"verbose" - Sets or resets verbose mode</h2>
 <keyword name="verbose"/>

src/lay/lay/doc/about/drc_ref_layer.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE language SYSTEM "klayout_doc.dtd">
 
-<!-- generated by /home/matthias/klayout/master/scripts/extract_doc.rb  -->
+<!-- generated by /home/matthias/klayout/dvb/scripts/extract_doc.rb  -->
 <!-- DO NOT EDIT! -->
 
 <doc>
@@ -225,7 +225,7 @@ deliver objects that can be converted into polygons. Such objects are of class <
 <p>
 This method produces markers on the corners of the polygons. An angle criterion can be given which
 selects corners based on the angle of the connecting edges. Positive angles indicate a left turn
-while negative angles indicate a right turn. Since polygons are oriented clockwise, postive angles
+while negative angles indicate a right turn. Since polygons are oriented clockwise, positive angles
 indicate concave corners while negative ones indicate convex corners.
 </p><p>
 The markers generated can be point-like edges or small 2x2 DBU boxes. The latter is the default.
@@ -584,6 +584,18 @@ The following images show the effect of the extents method:
 Applies to edge pair collections only.
 Returns the first edges of the edge pairs in the collection.
 </p>
+<h2>"flatten" - Flattens the layer</h2>
+<keyword name="flatten"/>
+<a name="flatten"/><p>Usage:</p>
+<ul>
+<li><tt>layer.flatten</tt></li>
+</ul>
+<p>
+If the layer already is a flat one, this method does nothing.
+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 polygons, edges or edge pairs.
+</p>
 <h2>"holes" - Selects all polygon holes from the input</h2>
 <keyword name="holes"/>
 <a name="holes"/><p>Usage:</p>
@@ -759,6 +771,12 @@ is composed of multiple pieces, this method will not return true.
 <p>
 See <a href="#clean">clean</a> for a discussion of the clean state.
 </p>
+<h2>"is_deep?" - Returns true, if the layer is a deep (hierarchical) layer</h2>
+<keyword name="is_deep?"/>
+<a name="is_deep?"/><p>Usage:</p>
+<ul>
+<li><tt>layer.is_deep?</tt></li>
+</ul>
 <h2>"is_empty?" - Returns true, if the layer is empty</h2>
 <keyword name="is_empty?"/>
 <a name="is_empty?"/><p>Usage:</p>

src/lay/lay/doc/about/drc_ref_netter.xml

@@ -0,0 +1,174 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE language SYSTEM "klayout_doc.dtd">
+
+<!-- generated by /home/matthias/klayout/dvb/scripts/extract_doc.rb  -->
+<!-- DO NOT EDIT! -->
+
+<doc>
+<title>DRC Reference: Netter object</title>
+<keyword name="Netter"/>
+<p>
+The Netter object provides services related to network extraction
+from a layout. The relevant methods of this object are available
+as global functions too where they act on a default incarnation
+of the netter. Usually it's not required to instantiate a Netter
+object, but it serves as a container for this functionality.
+</p><p>
+An individual netter object can be created, if the netter results
+need to be kept for multiple extractions. If you really need
+a Netter object, use the global <a href="#netter">netter</a> function:
+</p><p>
+<pre>
+# create a new Netter object:
+nx = netter
+nx.connect(poly, contact)
+...
+</pre>
+</p><p>
+Network formation:
+</p><p>
+A basic Service the Netter object provides is the formation of 
+connected networks of conductive shapes. To do so, the Netter
+must be given a connection specification. This happens by calling
+"connect" with two polygon layers. The Netter will then regard all
+overlaps of shapes on these layers as connections between the
+respective materials. Networks are the basis for netlist extraction,
+network geometry deduction and the antenna check.
+</p><p>
+Connections can be cleared with "clear_connections". If not, 
+connections add atop of the already defined ones. Here is an 
+example for the antenna check:
+</p><p>
+<pre>
+# build connction of poly+gate to metal1
+connect(gate, poly)
+connect(poly, contact)
+connect(contact, metal1)
+
+# runs an antenna check for metal1 with a ratio of 50
+m1_antenna_errors = antenna_check(gate, metal1, 50.0)
+
+# add connections to metal2
+connect(metal1, via1)
+connect(via1, metal2)
+
+# runs an antenna check for metal2 with a ratio of 70.0
+m2_antenna_errors = antenna_check(gate, metal2, 70.0)
+
+# this will remove all connections made
+clear_connections
+...
+</pre>
+</p><p>
+Further functionality of the Netter object:
+</p><p>
+More methods will be added in the future to support network-related features.
+</p>
+<h2-index/>
+<h2>"antenna_check" - Performs an antenna check</h2>
+<keyword name="antenna_check"/>
+<a name="antenna_check"/><p>Usage:</p>
+<ul>
+<li><tt>antenna_check(gate, metal, ratio, [ diode_specs ... ])</tt></li>
+</ul>
+<p>
+The antenna check is used to avoid plasma induced damage. Physically, 
+the damage happes if during the manufacturing of a metal layer with
+plasma etching charge accumulates on the metal islands. On reaching a
+certain threshold, this charge may discarge over gate oxide attached of 
+devices attached to such metal areas hence damaging it.
+</p><p>
+Antenna checks are performed by collecting all connected nets up to
+a certain metal layer and then computing the area of all metal shapes
+and all connected gates of a certain kind (e.g. thin and thick oxide gates).
+The ratio of metal area divided by the gate area must not exceed a certain
+threshold.
+</p><p>
+A simple antenna check is this:
+</p><p>
+<pre>
+poly = ... # poly layer
+diff = ... # diffusion layer
+contact = ... # contact layer
+metal1 = ... # metal layer
+
+# compute gate area
+gate = poly &amp; diff
+
+# note that gate and poly have to be included - gate is
+# a subset of poly, but forms the sensitive area
+connect(gate, poly)
+connect(poly, contact)
+connect(contact, metal1)
+errors = antenna_check(gate, metal1, 50.0)
+</pre>
+</p><p>
+Plasma induced damage can be rectified by including diodes
+which create a safe current path for discharging the metal
+islands. Such diodes can be identified with a recognition layer
+(usually the diffusion area of a certain kind). You can include
+such diode recognition layers in the antenna check. If a connection
+is detected to a diode, the respective network is skipped:
+</p><p>
+<pre>
+...
+diode = ... # diode recognition layer
+
+connect(diode, contact)
+errors = antenna_check(gate, metal1, 50.0, diode)
+</pre>
+</p><p>
+You can also make diode connections decreases the
+sensitivity of the antenna check depending on the size
+of the diode. The following specification makes 
+diode connections increase the ratio threshold by
+10 per square micrometer of diode area:
+</p><p>
+<pre>
+...
+diode = ... # diode recognition layer
+
+connect(diode, contact)
+# each square micrometer of diode area connected to a network
+# will add 10 to the ratio:
+errors = antenna_check(gate, metal1, 50.0, [ diode, 10.0 ])
+</pre>
+</p><p>
+Multiple diode specifications are allowed. Just add them 
+to the antenna_check call.
+</p><p>
+The error shapes produced by the antenna check are a copy
+of the metal shapes on the metal layers of each network 
+violating the antenna rule.
+</p>
+<h2>"clear_connections" - Clears all connections stored so far</h2>
+<keyword name="clear_connections"/>
+<a name="clear_connections"/><p>Usage:</p>
+<ul>
+<li><tt>clear_connections</tt></li>
+</ul>
+<p>
+See <a href="#connect">connect</a> for more details.
+</p>
+<h2>"connect" - Specifies a connection between two layers</h2>
+<keyword name="connect"/>
+<a name="connect"/><p>Usage:</p>
+<ul>
+<li><tt>connect(a, b)</tt></li>
+</ul>
+<p>
+a and b must be polygon layers. After calling this function, the
+Netter regards all overlapping or touching shapes on these layers
+to form an electrical connection between the materials formed by
+these layers. This also implies intra-layer connections: shapes
+on these layers touching or overlapping other shapes on these
+layers will form bigger, electrically connected areas.
+</p><p>
+Multiple connect calls must be made to form larger connectivity
+stacks across multiple layers. Such stacks may include forks and
+joins.
+</p><p>
+Connections are accumulated. The connections defined so far
+can be cleared with <a href="#clear_connections">clear_connections</a>.
+</p>
+</doc>

src/lay/lay/doc/about/drc_ref_source.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE language SYSTEM "klayout_doc.dtd">
 
-<!-- generated by /home/matthias/klayout/master/scripts/extract_doc.rb  -->
+<!-- generated by /home/matthias/klayout/dvb/scripts/extract_doc.rb  -->
 <!-- DO NOT EDIT! -->
 
 <doc>

src/lay/lay/layHelpResources.qrc

@@ -134,6 +134,7 @@
         <file alias="drc_ref_layer.xml">doc/about/drc_ref_layer.xml</file>
         <file alias="drc_ref_source.xml">doc/about/drc_ref_source.xml</file>
         <file alias="drc_ref_global.xml">doc/about/drc_ref_global.xml</file>
+        <file alias="drc_ref_netter.xml">doc/about/drc_ref_netter.xml</file>
         <file alias="packages.xml">doc/about/packages.xml</file>
     </qresource>
     <qresource prefix="/help/manual">