Very minor doc enhancements and cleanup

resources/doc/help_dev.xml

@@ -19,8 +19,8 @@
 -->
 
 <!--
-This is an example file to showcase what kind of panels INIshell can construct from XML.
-It is meant for people who want to use INIshell to control their own simulation software.
+This is the developer's guide which is meant for people who want to use INIshell to control
+their own simulation software. It showcases all panels and lists their options.
 -->
 
 <inishell_config>

resources/settings_dialog.xml

@@ -25,8 +25,8 @@ For changes, note that the keys used here are hardcoded in INIshell also.
 
 <inishell_config>
 
-<parameter type="label" label="&lt;h3&gt;&lt;i&gt;INIshell&lt;/i&gt; settings&lt;/h3&gt;" color="important">
-	<section name="Settings" color="important"/>
+	<parameter type="label" label="&lt;h3&gt;&lt;i&gt;INIshell&lt;/i&gt; settings&lt;/h3&gt;" color="important">
+		<section name="Settings" color="important"/>
 	</parameter>
 	<parameter type="helptext" wrap="true" section="settings">
 		<help>Press ESC or the &lt;b&gt;&lt;code&gt;x&lt;/code&gt;&lt;/b&gt; button to close the settings. Use the "Clear INI settings" toolbar button to reset to default values.&lt;br&gt;Don't forget to &lt;b&gt;Click to save settings&lt;/b&gt; when you are done!</help>

src/gui/PreviewWindow.cc

@@ -289,8 +289,8 @@ void PreviewWindow::closeEvent(QCloseEvent *event)
 }
 
 /**
- * @brief Event listener for the ESC key.
- * @details Close the Preview on pressing ESC.
+ * @brief Event listener for key presses.
+ * @details Close the Preview, add tab, or show the logger.
  * @param event The key press event that is received.
  */
 void PreviewWindow::keyPressEvent(QKeyEvent *event)

src/gui/WorkflowPanel.cc

@@ -65,7 +65,6 @@ WorkflowPanel::WorkflowPanel(QWidget *parent) : QWidget(parent)
 	path_label->setWordWrap(true);
 	path_label->setStyleSheet("QLabel {color: " + colors::getQColor("important").name() + "}");
 
-
 	workflow_container_->addItem(applications_, tr("Applications"));
 	//: Translation hint: This is for the workflow panel on the left side.
 	workflow_container_->addItem(simulations_, tr("Simulations"));

src/gui_elements/Atomic.cc

@@ -121,7 +121,7 @@ void Atomic::setPrimaryWidget(QWidget *primary_widget, const bool &set_object_na
 	if (set_object_name) //template panels may want to do this themselves (handling substitutions)
 		this->setObjectName(getQtKey(getId()));
 	QObject *const property_watcher( new PropertyWatcher(primary_widget) );
-	this->connect(property_watcher, SIGNAL(changedValue()), SLOT(onPropertySet()));
+	this->connect(property_watcher, SIGNAL(changedValue()), SLOT(onPropertySet())); //old style for easy delegation
 	this->installEventFilter(property_watcher);
 	if (!no_styles) //panels that style different widgets than the primary one (e. g. Choice)
 		setDefaultPanelStyles(this->property("ini_value").toString());
@@ -237,7 +237,7 @@ void Atomic::setLayoutMargins(QLayout *layout)
  * @param[in] force Add a Helptext even if it's empty (used by panels that can change the text).
  */
 Helptext * Atomic::addHelp(QHBoxLayout *layout, const QDomNode &options, const bool& tight, const bool &force)
-{ //changes here might have to be mirrored in other places, e. g. Choise::setOptions()
+{ //changes here might have to be mirrored in other places, e. g. Choice::setOptions()
 	QDomElement help_element( options.firstChildElement("help") ); //dedicated <help> tag if there is one
 	if (help_element.isNull())
 		help_element = options.firstChildElement("h"); //shortcut notation

src/gui_elements/Datepicker.cc

@@ -78,6 +78,7 @@ Datepicker::Datepicker(const QString &section, const QString &key, const QDomNod
 	key_filter_ = new DateKeyPressFilter;
 	datepicker_->installEventFilter(key_filter_);
 
+	/* main layout */
 	auto *datepicker_layout( new QHBoxLayout );
 	setLayoutMargins(datepicker_layout);
 	datepicker_layout->addWidget(key_label, 0, Qt::AlignLeft);
@@ -129,8 +130,8 @@ void Datepicker::onPropertySet()
 
 	/*
 	 * In checkValue() we always receive a date because the widget can't be empty.
-	 * So we catch this case early here (where an empty value can come from an INI
-	 * file for example) and style "empty" manually.
+	 * So we catch this case early here (where an empty value can come from XML
+	 * for example) and style "empty" manually.
 	 */
 	if (text_to_set.isEmpty()) {
 		QTimer::singleShot(1, this, [=]{ setEmpty(true); });

src/main/INIParser.cc

@@ -346,7 +346,7 @@ bool SectionList::removeSection(const QString &str_section)
 			}
 		}
 		section_list_.erase(lit);
-		return  true;
+		return true;
 	}
 	return false; //section did not exist
 }

src/main/common.cc

@@ -77,7 +77,7 @@ void MessageHandler::handleMessage(QtMsgType type, const QString &description, c
 QStringList getSearchDirs(const bool &include_user_set, const bool &include_nonexistent_folders)
 {
 
-	/* hardcoded directories, the system specific parts are handled by Qt */
+	/* hardcoded directories, the system specific paths are partly handled by Qt */
 	QStringList locations;
 	locations << "."; //the application's current directory
 	os::getSystemLocations(locations); //update list with OS specific search paths

src/main/expressions.cc

@@ -89,6 +89,12 @@ bool checkExpression(const QString &expression, bool &evaluation_success,
 	return false;
 }
 
+/**
+ * @brief Parse "substitutions" option into container.
+ * @details This is a helper function to translate XML settings to an internal container.
+ * @param[in] options XML options for the panel.
+ * @return Vector of desired. substitutions and their replacements.
+ */
 std::vector< std::pair<QString, QString> > parseSubstitutions(const QDomNode &options)
 {
 	/*
@@ -96,6 +102,12 @@ std::vector< std::pair<QString, QString> > parseSubstitutions(const QDomNode &op
 	 * will prepare the expression for tinyexpr first, enabling e. g. substitutions.
 	 * In order not to hard code a list of substitutions which may differ for different
 	 * software, these replacements can be user-set.
+	 *
+	 * Consider the Particle Filter as an example. The PF knows the variable "xx" but tinyexpr
+	 * does not. It is replaced by a numeric value by the PF before passing the expression to
+	 * tinyexpr. With substitutions you can mimick this and replace all "xx" with "1" (or
+	 * whatever fits your case) so that INIshell can correctly style it as valid - because
+	 * it is valid now for tinyexpr.
 	 */
 	std::vector<std::pair<QString, QString>> substitutions;
 	for (QDomElement op = options.firstChildElement("substitution"); !op.isNull();

tests/run_tests.sh

@@ -19,7 +19,7 @@ if [ -z "$difference" ]; then
 else
       echo "[E] The ini reader did not produce the expected result! Difference:"
       echo "$difference"
-      echo "[I] NOTE: Make sure you have set whitespace handling to 'USER' in INIshell's settings!"
+      echo "[i] NOTE: Make sure you have set whitespace handling to 'USER' in INIshell's settings!"
 fi
 
 echo "*** All done"