Documented the purpose of various perl modules.

24 files changed, 76 insertions, 2 deletions

diff --git a/lib/Slic3r.pm b/lib/Slic3r.pm
index e7dfd102b..7dfa9063f 100644
--- a/lib/Slic3r.pm
+++ b/lib/Slic3r.pm
@@ -20,6 +20,7 @@ sub debugf {
 # load threads before Moo as required by it
 our $have_threads;
 BEGIN {
+    # Test, whether the perl was compiled with ithreads support and ithreads actually work.
     use Config;
     $have_threads = $Config{useithreads} && eval "use threads; use threads::shared; use Thread::Queue; 1";
     warn "threads.pm >= 1.96 is required, please update\n" if $have_threads && $threads::VERSION < 1.96;
@@ -27,6 +28,13 @@ BEGIN {
     ### temporarily disable threads if using the broken Moo version
     use Moo;
     $have_threads = 0 if $Moo::VERSION == 1.003000;
+
+    # Disable multi threading completely by an environment value.
+    # This is useful for debugging as the Perl debugger does not work
+    # in multi-threaded context at all.
+    # A good interactive perl debugger is the ActiveState Komodo IDE
+    # or the EPIC http://www.epic-ide.org/
+    $have_threads = 0 if (defined($ENV{'SLIC3R_SINGLETHREADED'}) && $ENV{'SLIC3R_SINGLETHREADED'} == 1)
 }
 
 warn "Running Slic3r under Perl 5.16 is neither supported nor recommended\n"
diff --git a/lib/Slic3r/GUI/2DBed.pm b/lib/Slic3r/GUI/2DBed.pm
index 6a3e26a9f..3f116cf9c 100644
--- a/lib/Slic3r/GUI/2DBed.pm
+++ b/lib/Slic3r/GUI/2DBed.pm
@@ -1,3 +1,5 @@
+# Bed shape dialog
+
 package Slic3r::GUI::2DBed;
 use strict;
 use warnings;
diff --git a/lib/Slic3r/GUI/3DScene.pm b/lib/Slic3r/GUI/3DScene.pm
index d2186d870..893f62d40 100644
--- a/lib/Slic3r/GUI/3DScene.pm
+++ b/lib/Slic3r/GUI/3DScene.pm
@@ -1347,6 +1347,8 @@ sub _expolygons_to_verts {
     gluDeleteTess($tess);
 }
 
+# Fill in the $qverts and $tverts with quads and triangles
+# for the extrusion $entity.
 sub _extrusionentity_to_verts {
     my ($self, $entity, $top_z, $copy, $qverts, $tverts) = @_;
     
@@ -1379,8 +1381,16 @@ sub _extrusionentity_to_verts {
         }
     }
     # Calling the C++ implementation Slic3r::_3DScene::_extrusionentity_to_verts_do()
+    # This adds new vertices to the $qverts and $tverts.
     Slic3r::GUI::_3DScene::_extrusionentity_to_verts_do($lines, $widths, $heights,
-        $closed, $top_z, $copy, $qverts, $tverts);
+        $closed, 
+        # Top height of the extrusion.
+        $top_z, 
+        # $copy is not used here.
+        $copy,
+        # GLVertexArray object: C++ class maintaining an std::vector<float> for coords and normals.
+        $qverts,
+        $tverts);
 }
 
 sub object_idx {
diff --git a/lib/Slic3r/GUI/BedShapeDialog.pm b/lib/Slic3r/GUI/BedShapeDialog.pm
index 49c8b9e07..ed6fb5cde 100644
--- a/lib/Slic3r/GUI/BedShapeDialog.pm
+++ b/lib/Slic3r/GUI/BedShapeDialog.pm
@@ -1,3 +1,6 @@
+# The bed shape dialog.
+# The dialog opens from Print Settins tab -> Bed Shape: Set...
+
 package Slic3r::GUI::BedShapeDialog;
 use strict;
 use warnings;
diff --git a/lib/Slic3r/GUI/BonjourBrowser.pm b/lib/Slic3r/GUI/BonjourBrowser.pm
index 469d0302e..c7513165f 100644
--- a/lib/Slic3r/GUI/BonjourBrowser.pm
+++ b/lib/Slic3r/GUI/BonjourBrowser.pm
@@ -1,3 +1,5 @@
+# A tiny dialog to select an OctoPrint device to print to.
+
 package Slic3r::GUI::BonjourBrowser;
 use strict;
 use warnings;
diff --git a/lib/Slic3r/GUI/ConfigWizard.pm b/lib/Slic3r/GUI/ConfigWizard.pm
index 008b76f25..b90837937 100644
--- a/lib/Slic3r/GUI/ConfigWizard.pm
+++ b/lib/Slic3r/GUI/ConfigWizard.pm
@@ -1,3 +1,6 @@
+# The config wizard is executed when the Slic3r is first started.
+# The wizard helps the user to specify the 3D printer properties.
+
 package Slic3r::GUI::ConfigWizard;
 use strict;
 use warnings;
diff --git a/lib/Slic3r/GUI/Controller.pm b/lib/Slic3r/GUI/Controller.pm
index 6d2d16b9e..c6a568f82 100644
--- a/lib/Slic3r/GUI/Controller.pm
+++ b/lib/Slic3r/GUI/Controller.pm
@@ -1,3 +1,7 @@
+# The "Controller" tab to control the printer using serial / USB.
+# This feature is rarely used. Much more often, the firmware reads the G-codes from a SD card.
+# May there be multiple subtabs per each printer connected?
+
 package Slic3r::GUI::Controller;
 use strict;
 use warnings;
diff --git a/lib/Slic3r/GUI/Controller/ManualControlDialog.pm b/lib/Slic3r/GUI/Controller/ManualControlDialog.pm
index ebd0031a9..ac997730d 100644
--- a/lib/Slic3r/GUI/Controller/ManualControlDialog.pm
+++ b/lib/Slic3r/GUI/Controller/ManualControlDialog.pm
@@ -1,3 +1,5 @@
+# A printer "Controller" -> "ManualControlDialog" subtab, opened per 3D printer connected?
+
 package Slic3r::GUI::Controller::ManualControlDialog;
 use strict;
 use warnings;
diff --git a/lib/Slic3r/GUI/MainFrame.pm b/lib/Slic3r/GUI/MainFrame.pm
index d97ad22ef..24368fe63 100644
--- a/lib/Slic3r/GUI/MainFrame.pm
+++ b/lib/Slic3r/GUI/MainFrame.pm
@@ -1,3 +1,5 @@
+# The main frame, the parent of all.
+
 package Slic3r::GUI::MainFrame;
 use strict;
 use warnings;
diff --git a/lib/Slic3r/GUI/Notifier.pm b/lib/Slic3r/GUI/Notifier.pm
index a2242bcdf..eb548d014 100644
--- a/lib/Slic3r/GUI/Notifier.pm
+++ b/lib/Slic3r/GUI/Notifier.pm
@@ -1,3 +1,6 @@
+# Notify about the end of slicing.
+# The notifications are sent out using the Growl protocol if installed, and using DBus XWindow protocol.
+
 package Slic3r::GUI::Notifier;
 use Moo;
 
diff --git a/lib/Slic3r/GUI/OptionsGroup.pm b/lib/Slic3r/GUI/OptionsGroup.pm
index b64fc8cb7..382dbc744 100644
--- a/lib/Slic3r/GUI/OptionsGroup.pm
+++ b/lib/Slic3r/GUI/OptionsGroup.pm
@@ -1,3 +1,5 @@
+# A dialog group object. Used by the Tab, SimpleTab, Preferences dialog, ManualControlDialog etc.
+
 package Slic3r::GUI::OptionsGroup;
 use Moo;
 
diff --git a/lib/Slic3r/GUI/Plater.pm b/lib/Slic3r/GUI/Plater.pm
index 4c8283c95..55e6f03c8 100644
--- a/lib/Slic3r/GUI/Plater.pm
+++ b/lib/Slic3r/GUI/Plater.pm
@@ -1,3 +1,5 @@
+# The "Plater" tab. It contains the "3D", "2D", "Preview" and "Layers" subtabs.
+
 package Slic3r::GUI::Plater;
 use strict;
 use warnings;
diff --git a/lib/Slic3r/GUI/Plater/2D.pm b/lib/Slic3r/GUI/Plater/2D.pm
index 24bf80135..8fb8908e1 100644
--- a/lib/Slic3r/GUI/Plater/2D.pm
+++ b/lib/Slic3r/GUI/Plater/2D.pm
@@ -1,3 +1,6 @@
+# 2D preview on the platter.
+# 3D objects are visualized by their convex hulls.
+
 package Slic3r::GUI::Plater::2D;
 use strict;
 use warnings;
diff --git a/lib/Slic3r/GUI/Plater/2DToolpaths.pm b/lib/Slic3r/GUI/Plater/2DToolpaths.pm
index 66d669b11..e153e4db2 100644
--- a/lib/Slic3r/GUI/Plater/2DToolpaths.pm
+++ b/lib/Slic3r/GUI/Plater/2DToolpaths.pm
@@ -1,5 +1,6 @@
 # 2D preview of the tool paths of a single layer, using a thin line.
 # OpenGL is used to render the paths.
+# Vojtech also added a 2D simulation of under/over extrusion in a single layer.
 
 package Slic3r::GUI::Plater::2DToolpaths;
 use strict;
diff --git a/lib/Slic3r/GUI/Plater/ObjectCutDialog.pm b/lib/Slic3r/GUI/Plater/ObjectCutDialog.pm
index a523fb085..cfdeba649 100644
--- a/lib/Slic3r/GUI/Plater/ObjectCutDialog.pm
+++ b/lib/Slic3r/GUI/Plater/ObjectCutDialog.pm
@@ -1,3 +1,6 @@
+# Cut an object at a Z position, keep either the top or the bottom of the object.
+# This dialog gets opened with the "Cut..." button above the platter.
+
 package Slic3r::GUI::Plater::ObjectCutDialog;
 use strict;
 use warnings;
diff --git a/lib/Slic3r/GUI/Plater/ObjectPartsPanel.pm b/lib/Slic3r/GUI/Plater/ObjectPartsPanel.pm
index a75be5902..4882233a6 100644
--- a/lib/Slic3r/GUI/Plater/ObjectPartsPanel.pm
+++ b/lib/Slic3r/GUI/Plater/ObjectPartsPanel.pm
@@ -1,3 +1,6 @@
+# Configuration of mesh modifiers and their parameters.
+# This panel is inserted into ObjectSettingsDialog.
+
 package Slic3r::GUI::Plater::ObjectPartsPanel;
 use strict;
 use warnings;
diff --git a/lib/Slic3r/GUI/Plater/ObjectSettingsDialog.pm b/lib/Slic3r/GUI/Plater/ObjectSettingsDialog.pm
index c920b796a..d7909816b 100644
--- a/lib/Slic3r/GUI/Plater/ObjectSettingsDialog.pm
+++ b/lib/Slic3r/GUI/Plater/ObjectSettingsDialog.pm
@@ -1,3 +1,7 @@
+# This dialog opens up when double clicked on an object line in the list at the right side of the platter.
+# One may load additional STLs and additional modifier STLs,
+# one may change the properties of the print per each modifier mesh or a Z-span.
+
 package Slic3r::GUI::Plater::ObjectSettingsDialog;
 use strict;
 use warnings;
diff --git a/lib/Slic3r/GUI/Plater/OverrideSettingsPanel.pm b/lib/Slic3r/GUI/Plater/OverrideSettingsPanel.pm
index 1b976c10e..e848b7638 100644
--- a/lib/Slic3r/GUI/Plater/OverrideSettingsPanel.pm
+++ b/lib/Slic3r/GUI/Plater/OverrideSettingsPanel.pm
@@ -1,3 +1,6 @@
+# Included in ObjectSettingsDialog -> ObjectPartsPanel.
+# Maintains, displays, adds and removes overrides of slicing parameters for an object and its modifier mesh.
+
 package Slic3r::GUI::Plater::OverrideSettingsPanel;
 use strict;
 use warnings;
diff --git a/lib/Slic3r/GUI/Preferences.pm b/lib/Slic3r/GUI/Preferences.pm
index ed210d229..431f642d6 100644
--- a/lib/Slic3r/GUI/Preferences.pm
+++ b/lib/Slic3r/GUI/Preferences.pm
@@ -1,3 +1,5 @@
+# Preferences dialog, opens from Menu: File->Preferences
+
 package Slic3r::GUI::Preferences;
 use Wx qw(:dialog :id :misc :sizer :systemsettings wxTheApp);
 use Wx::Event qw(EVT_BUTTON EVT_TEXT_ENTER);
diff --git a/lib/Slic3r/GUI/ProgressStatusBar.pm b/lib/Slic3r/GUI/ProgressStatusBar.pm
index b901740a9..32fd52680 100644
--- a/lib/Slic3r/GUI/ProgressStatusBar.pm
+++ b/lib/Slic3r/GUI/ProgressStatusBar.pm
@@ -1,3 +1,5 @@
+# Status bar at the bottom of the main screen.
+
 package Slic3r::GUI::ProgressStatusBar;
 use strict;
 use warnings;
diff --git a/lib/Slic3r/GUI/Projector.pm b/lib/Slic3r/GUI/Projector.pm
index 2731b3e51..a89181371 100644
--- a/lib/Slic3r/GUI/Projector.pm
+++ b/lib/Slic3r/GUI/Projector.pm
@@ -1,3 +1,5 @@
+# DLP Projector screen for the SLA (stereolitography) print process
+
 package Slic3r::GUI::Projector;
 use strict;
 use warnings;
diff --git a/lib/Slic3r/GUI/SimpleTab.pm b/lib/Slic3r/GUI/SimpleTab.pm
index 888ff0e9b..13c6efc88 100644
--- a/lib/Slic3r/GUI/SimpleTab.pm
+++ b/lib/Slic3r/GUI/SimpleTab.pm
@@ -1,3 +1,6 @@
+# The "Simple" Print Settings tab.
+# The "Simple" mode is enabled by File->Preferences dialog.
+
 package Slic3r::GUI::SimpleTab;
 use strict;
 use warnings;
diff --git a/lib/Slic3r/GUI/Tab.pm b/lib/Slic3r/GUI/Tab.pm
index 4f8defd99..72e798b5e 100644
--- a/lib/Slic3r/GUI/Tab.pm
+++ b/lib/Slic3r/GUI/Tab.pm
@@ -1,3 +1,6 @@
+# The "Expert" tab at the right of the main tabbed window.
+# The "Expert" is enabled by File->Preferences dialog.
+
 package Slic3r::GUI::Tab;
 use strict;
 use warnings;
diff --git a/lib/Slic3r/Test/SectionCut.pm b/lib/Slic3r/Test/SectionCut.pm
index 04106d46f..8cfda13d1 100644
--- a/lib/Slic3r/Test/SectionCut.pm
+++ b/lib/Slic3r/Test/SectionCut.pm
@@ -1,4 +1,6 @@
-# Slices at the XZ plane, for debugging purposes.
+# 2D cut in the XZ plane through the toolpaths.
+# For debugging purposes.
+
 package Slic3r::Test::SectionCut;
 use Moo;