Ported from the playground branch. Various documentation and optimization.

xs/src/libslic3r/Config.hpp

@@ -14,9 +14,11 @@
 
 namespace Slic3r {
 
+// Name of the configuration option.
 typedef std::string t_config_option_key;
 typedef std::vector<std::string> t_config_option_keys;
 
+// A generic value of a configuration option.
 class ConfigOption {
     public:
     virtual ~ConfigOption() {};
@@ -31,6 +33,7 @@ class ConfigOption {
     friend bool operator!= (const ConfigOption &a, const ConfigOption &b);
 };
 
+// Value of a single valued option (bool, int, float, string, point, enum)
 template <class T>
 class ConfigOptionSingle : public ConfigOption {
     public:
@@ -44,12 +47,14 @@ class ConfigOptionSingle : public ConfigOption {
     };
 };
 
+// Value of a vector valued option (bools, ints, floats, strings, points)
 class ConfigOptionVectorBase : public ConfigOption {
     public:
     virtual ~ConfigOptionVectorBase() {};
     virtual std::vector<std::string> vserialize() const = 0;
 };
 
+// Value of a vector valued option (bools, ints, floats, strings, points), template
 template <class T>
 class ConfigOptionVector : public ConfigOptionVectorBase
 {
@@ -436,6 +441,7 @@ class ConfigOptionBools : public ConfigOptionVector<bool>
     };
 };
 
+// Map from an enum name to an enum integer value.
 typedef std::map<std::string,int> t_config_enum_values;
 
 template <class T>
@@ -461,11 +467,14 @@ class ConfigOptionEnum : public ConfigOptionSingle<T>
         return true;
     };
 
+    // Map from an enum name to an enum integer value.
+    //FIXME The map is called often, it shall be initialized statically.
     static t_config_enum_values get_enum_values();
 };
 
-/* We use this one in DynamicConfig objects, otherwise it's better to use
-   the specialized ConfigOptionEnum<T> containers. */
+// Generic enum configuration value.
+// We use this one in DynamicConfig objects when creating a config value object for ConfigOptionType == coEnum.
+// In the StaticConfig, it is better to use the specialized ConfigOptionEnum<T> containers.
 class ConfigOptionEnumGeneric : public ConfigOptionInt
 {
     public:
@@ -485,57 +494,117 @@ class ConfigOptionEnumGeneric : public ConfigOptionInt
     };
 };
 
+// Type of a configuration value.
 enum ConfigOptionType {
     coNone,
+    // single float
     coFloat,
+    // vector of floats
     coFloats,
+    // single int
     coInt,
+    // vector of ints
     coInts,
+    // single string
     coString,
+    // vector of strings
     coStrings,
+    // percent value. Currently only used for infill.
     coPercent,
+    // a fraction or an absolute value
     coFloatOrPercent,
+    // single 2d point. Currently not used.
     coPoint,
+    // vector of 2d points. Currently used for the definition of the print bed and for the extruder offsets.
     coPoints,
+    // single boolean value
     coBool,
+    // vector of boolean values
     coBools,
+    // a generic enum
     coEnum,
 };
 
+// Definition of a configuration value for the purpose of GUI presentation, editing, value mapping and config file handling.
 class ConfigOptionDef
 {
     public:
+    // What type? bool, int, string etc.
     ConfigOptionType type;
+    // Default value of this option. The default value object is owned by ConfigDef, it is released in its destructor.
     ConfigOption* default_value;
+
+    // Usually empty. 
+    // Special values - "i_enum_open", "f_enum_open" to provide combo box for int or float selection,
+    // "select_open" - to open a selection dialog (currently only a serial port selection).
     std::string gui_type;
+    // Usually empty. Otherwise "serialized" or "show_value"
+    // The flags may be combined.
+    // "serialized" - vector valued option is entered in a single edit field. Values are separated by a semicolon.
+    // "show_value" - even if enum_values / enum_labels are set, still display the value, not the enum label.
     std::string gui_flags;
+    // Label of the GUI input field.
+    // In case the GUI input fields are grouped in some views, the label defines a short label of a grouped value,
+    // while full_label contains a label of a stand-alone field.
+    // The full label is shown, when adding an override parameter for an object or a modified object.
     std::string label;
     std::string full_label;
+    // Category of a configuration field, from the GUI perspective.
+    // One of: "Layers and Perimeters", "Infill", "Support material", "Speed", "Extruders", "Advanced", "Extrusion Width"
     std::string category;
+    // A tooltip text shown in the GUI.
     std::string tooltip;
+    // Text right from the input field, usually a unit of measurement.
     std::string sidetext;
+    // Format of this parameter on a command line.
     std::string cli;
+    // Set for type == coFloatOrPercent.
+    // It provides a link to a configuration value, of which this option provides a ratio.
+    // For example, 
+    // For example external_perimeter_speed may be defined as a fraction of perimeter_speed.
     t_config_option_key ratio_over;
+    // True for multiline strings.
     bool multiline;
+    // For text input: If true, the GUI text box spans the complete page width.
     bool full_width;
+    // Not editable. Currently only used for the display of the number of threads.
     bool readonly;
+    // Height of a multiline GUI text box.
     int height;
+    // Optional width of an input field.
     int width;
+    // <min, max> limit of a numeric input.
+    // If not set, the <min, max> is set to <INT_MIN, INT_MAX>
+    // By setting min=0, only nonnegative input is allowed.
     int min;
     int max;
+    // Legacy names for this configuration option.
+    // Used when parsing legacy configuration file.
     std::vector<t_config_option_key> aliases;
+    // Sometimes a single value may well define multiple values in a "beginner" mode.
+    // Currently used for aliasing "solid_layers" to "top_solid_layers", "bottom_solid_layers".
     std::vector<t_config_option_key> shortcut;
+    // Definition of values / labels for a combo box.
+    // Mostly used for enums (when type == coEnum), but may be used for ints resp. floats, if gui_type is set to "i_enum_open" resp. "f_enum_open".
     std::vector<std::string> enum_values;
     std::vector<std::string> enum_labels;
+    // For enums (when type == coEnum). Maps enum_values to enums.
+    // Initialized by ConfigOptionEnum<xxx>::get_enum_values()
     t_config_enum_values enum_keys_map;
-    
+
     ConfigOptionDef() : type(coNone), default_value(NULL),
                         multiline(false), full_width(false), readonly(false),
                         height(-1), width(-1), min(INT_MIN), max(INT_MAX) {};
 };
 
+// Map from a config option name to its definition.
+// The definition does not carry an actual value of the config option, only its constant default value.
+// t_config_option_key is std::string
 typedef std::map<t_config_option_key,ConfigOptionDef> t_optiondef_map;
 
+// Definition of configuration values for the purpose of GUI presentation, editing, value mapping and config file handling.
+// The configuration definition is static: It does not carry the actual configuration values,
+// but it carries the defaults of the configuration values.
 class ConfigDef
 {
     public:
@@ -545,9 +614,14 @@ class ConfigDef
     const ConfigOptionDef* get(const t_config_option_key &opt_key) const;
 };
 
+// An abstract configuration store.
 class ConfigBase
 {
     public:
+    // Definition of configuration values for the purpose of GUI presentation, editing, value mapping and config file handling.
+    // The configuration definition is static: It does not carry the actual configuration values,
+    // but it carries the defaults of the configuration values.
+    // ConfigBase does not own ConfigDef, it only references it.
     const ConfigDef* def;
     
     ConfigBase() : def(NULL) {};
@@ -562,11 +636,14 @@ class ConfigBase
     t_config_option_keys diff(ConfigBase &other);
     std::string serialize(const t_config_option_key &opt_key) const;
     bool set_deserialize(const t_config_option_key &opt_key, std::string str);
+
     double get_abs_value(const t_config_option_key &opt_key);
     double get_abs_value(const t_config_option_key &opt_key, double ratio_over);
     void setenv_();
 };
 
+// Configuration store with dynamic number of configuration values.
+// In Slic3r, the dynamic config is mostly used at the user interface layer.
 class DynamicConfig : public virtual ConfigBase
 {
     public:
@@ -585,13 +662,20 @@ class DynamicConfig : public virtual ConfigBase
     t_options_map options;
 };
 
+// Configuration store with a static definition of configuration values.
+// In Slic3r, the static configuration stores are during the slicing / g-code generation for efficiency reasons,
+// because the configuration values could be accessed directly.
 class StaticConfig : public virtual ConfigBase
 {
     public:
     StaticConfig() : ConfigBase() {};
+    // Gets list of config option names for each config option of this->def, which has a static counter-part defined by the derived object
+    // and which could be resolved by this->optptr(key) call.
     t_config_option_keys keys() const;
-    //virtual ConfigOption* optptr(const t_config_option_key &opt_key, bool create = false) = 0;
+    // Set all statically defined config options to their defaults defined by this->def.
     void set_defaults();
+    // The derived class has to implement optptr to resolve a static configuration value.
+    // virtual ConfigOption* optptr(const t_config_option_key &opt_key, bool create = false) = 0;
 };
 
 }