ui: Explain differences of errors and how to fix them (issue #501)

* added help button next to filters in error table
* added menu action Help -> Fixing Errors
* added help button on indexing dialog
* show help message after first time indexing with errors, if not seen already

bin/app/data/gui/tabbed_view/tabbed_view.css

@@ -121,3 +121,10 @@ QTableView QTableCornerButton::section {
 	border-bottom: 1px solid <color:table/table>;
 	border-top-left-radius: 10px;
 }
+
+#help_button {
+	background: transparent;
+	border: none;
+	/*margin: none;*/
+	/*padding: none;*/
+}

bin/app/user/ApplicationSettings_template.xml

@@ -90,6 +90,8 @@
 			<update_url><!-- STRING: url to new version download --></update_url>
 			<update_version><!-- VERSION: version of last check --></update_version>
 		</update_check>
+
+		<seen_error_help_message><!-- BOOL: whether user has been shown help message on errors after indexing --></seen_error_help_message>
 	</user>
 
 	<network>

src/lib/CMakeLists.txt

@@ -418,6 +418,7 @@ add_files(
 	utility/messaging/type/MessageSearch.h
 	utility/messaging/type/MessageSearchAutocomplete.h
 	utility/messaging/type/MessageSearchFullText.h
+	utility/messaging/type/MessageShowErrorHelpMessage.h
 	utility/messaging/type/MessageShowErrors.h
 	utility/messaging/type/MessageShowReference.h
 	utility/messaging/type/MessageShowScope.h

src/lib/component/controller/ErrorController.cpp

@@ -1,6 +1,7 @@
 #include "component/controller/ErrorController.h"
 
 #include "data/access/StorageAccess.h"
+#include "settings/ApplicationSettings.h"
 
 ErrorController::ErrorController(StorageAccess* storageAccess)
 	: m_storageAccess(storageAccess)
@@ -46,6 +47,29 @@ void ErrorController::handleMessage(MessageNewErrors* message)
 
 }
 
+void ErrorController::handleMessage(MessageShowErrorHelpMessage* message)
+{
+	ApplicationSettings* appSettings = ApplicationSettings::getInstance().get();
+	if (!message->force && appSettings->getSeenErrorHelpMessage())
+	{
+		return;
+	}
+
+	if (!message->force)
+	{
+		ErrorCountInfo info = m_storageAccess->getErrorCount();
+		if (!info.total)
+		{
+			return;
+		}
+	}
+
+	appSettings->setSeenErrorHelpMessage(true);
+	appSettings->save();
+
+	getView()->showErrorHelpMessage();
+}
+
 void ErrorController::handleMessage(MessageShowErrors* message)
 {
 	if (message->errorId)

src/lib/component/controller/ErrorController.h

@@ -5,6 +5,7 @@
 #include "utility/messaging/type/MessageClearErrorCount.h"
 #include "utility/messaging/type/MessageFinishedParsing.h"
 #include "utility/messaging/type/MessageNewErrors.h"
+#include "utility/messaging/type/MessageShowErrorHelpMessage.h"
 #include "utility/messaging/type/MessageShowErrors.h"
 
 #include "component/controller/Controller.h"
@@ -17,6 +18,7 @@ class ErrorController
 	, public MessageListener<MessageClearErrorCount>
 	, public MessageListener<MessageFinishedParsing>
 	, public MessageListener<MessageNewErrors>
+	, public MessageListener<MessageShowErrorHelpMessage>
 	, public MessageListener<MessageShowErrors>
 {
 public:
@@ -27,6 +29,7 @@ private:
 	virtual void handleMessage(MessageClearErrorCount* message);
 	virtual void handleMessage(MessageFinishedParsing* message);
 	virtual void handleMessage(MessageNewErrors* message);
+	virtual void handleMessage(MessageShowErrorHelpMessage* message);
 	virtual void handleMessage(MessageShowErrors* message);
 
 	ErrorView* getView() const;

src/lib/component/view/ErrorView.h

@@ -23,6 +23,8 @@ public:
 
 	virtual void setErrorCount(ErrorCountInfo info) = 0;
 	virtual void resetErrorLimit() = 0;
+
+	virtual void showErrorHelpMessage() = 0;
 };
 
 #endif // ERROR_VIEW_H

src/lib/settings/ApplicationSettings.cpp

@@ -506,6 +506,16 @@ void ApplicationSettings::setUpdateVersion(const Version& version)
 	}
 }
 
+bool ApplicationSettings::getSeenErrorHelpMessage() const
+{
+	return getValue<bool>("user/seen_error_help_message", false);
+}
+
+void ApplicationSettings::setSeenErrorHelpMessage(bool seen)
+{
+	setValue<bool>("user/seen_error_help_message", seen);
+}
+
 int ApplicationSettings::getPluginPort() const
 {
 	return getValue<int>("network/plugin_port", 6666);

src/lib/settings/ApplicationSettings.h

@@ -141,6 +141,9 @@ public:
 	Version getUpdateVersion() const;
 	void setUpdateVersion(const Version& version);
 
+	bool getSeenErrorHelpMessage() const;
+	void setSeenErrorHelpMessage(bool seen);
+
 	// network
 	int getPluginPort() const;
 	void setPluginPort(const int pluginPort);

src/lib/utility/messaging/type/MessageShowErrorHelpMessage.h

@@ -0,0 +1,23 @@
+#ifndef MESSAGE_SHOW_ERROR_HELP_MESSAGE_H
+#define MESSAGE_SHOW_ERROR_HELP_MESSAGE_H
+
+#include "utility/messaging/Message.h"
+
+class MessageShowErrorHelpMessage:
+	public Message<MessageShowErrorHelpMessage>
+{
+public:
+	MessageShowErrorHelpMessage(bool force = false)
+		: force(force)
+	{
+	}
+
+	static const std::string getStaticType()
+	{
+		return "MessageShowErrorHelpMessage";
+	}
+
+	const bool force;
+};
+
+#endif // MESSAGE_SHOW_ERROR_HELP_MESSAGE_H

src/lib_gui/qt/view/QtErrorView.cpp

@@ -13,6 +13,7 @@
 #include <QStandardItem>
 #include <QStyledItemDelegate>
 
+#include "qt/element/QtHelpButton.h"
 #include "qt/element/QtTable.h"
 #include "qt/utility/utilityQt.h"
 #include "qt/view/QtViewWidgetWrapper.h"
@@ -113,6 +114,28 @@ void QtErrorView::initView()
 		m_showErrors = createFilterCheckbox("Errors", m_errorFilter.error, checkboxes);
 		m_showNonIndexedFatals = createFilterCheckbox("Fatals in non-indexed files", m_errorFilter.unindexedFatal, checkboxes);
 		m_showNonIndexedErrors = createFilterCheckbox("Errors in non-indexed files", m_errorFilter.unindexedError, checkboxes);
+
+		m_helpButton = new QtHelpButton("Fixing Errors",
+			"Please read this if your project is showing errors after indexing.<br />"
+			"There are different types of errors:"
+			"<ul>"
+			"<li><b>Fatals</b> cause the indexer to stop. All or big parts of indexed information for the involved "
+			"source file is missing. <b>Make sure to fix all fatals.</li>"
+			"<li><b>Errors</b> are issues that the indexer considers as wrong code. Usually the indexer is able to "
+			"recover from these errors. The indexed information of the involved source file may not be complete, but "
+			"it is still useful.</li>"
+			"</ul>"
+			"You need to edit your Sourcetrail project and reindex it to fix errors. The displayed error messages are "
+			"generated by Sourcetrail's language specific indexers:"
+			"<ul>"
+			"<li><b>C/C++</b> error messages are generated by the <b>clang compiler frontend</b>.</li>"
+			"<li><b>Java</b> error messages are generated by the <b>Eclipse JDT library</b>.</li>"
+			"</ul>"
+			"You should be able to find information about errors you are not familiar with online. <b>Double click</b> "
+			"an error message in the table to select it for <b>copying</b>.<br />"
+		);
+		m_helpButton->setObjectName("help_button");
+		checkboxes->addWidget(m_helpButton);
 	}
 
 	checkboxes->addStretch();
@@ -239,6 +262,14 @@ void QtErrorView::resetErrorLimit()
 	errorFilterChanged(0, false);
 }
 
+void QtErrorView::showErrorHelpMessage()
+{
+	m_onQtThread([=]()
+	{
+		m_helpButton->click();
+	});
+}
+
 void QtErrorView::errorFilterChanged(int i)
 {
 	errorFilterChanged(i, true);
@@ -269,6 +300,8 @@ void QtErrorView::setStyleSheet() const
 	m_showNonIndexedErrors->setPalette(palette);
 	m_showNonIndexedFatals->setPalette(palette);
 
+	m_helpButton->setColor(QColor(ColorScheme::getInstance()->getColor("table/text/normal").c_str()));
+
 	m_table->updateRows();
 }
 

src/lib_gui/qt/view/QtErrorView.h

@@ -12,6 +12,7 @@ class QCheckBox;
 class QLabel;
 class QPushButton;
 class QStandardItemModel;
+class QtHelpButton;
 class QtTable;
 
 class QtErrorView
@@ -37,6 +38,8 @@ public:
 	virtual void setErrorCount(ErrorCountInfo info);
 	virtual void resetErrorLimit();
 
+	virtual void showErrorHelpMessage();
+
 private slots:
 	void errorFilterChanged(int i = 0);
 	void errorFilterChanged(int i, bool showErrors);
@@ -73,6 +76,8 @@ private:
 	QCheckBox* m_showNonIndexedErrors;
 	QCheckBox* m_showNonIndexedFatals;
 
+	QtHelpButton* m_helpButton;
+
 	QStandardItemModel* m_model;
 	QtTable* m_table;
 

src/lib_gui/qt/window/QtIndexingDialog.cpp

@@ -10,6 +10,7 @@
 #include "qt/element/QtHelpButton.h"
 #include "qt/element/QtProgressBar.h"
 #include "utility/messaging/type/MessageInterruptTasks.h"
+#include "utility/messaging/type/MessageShowErrorHelpMessage.h"
 #include "utility/ResourcePaths.h"
 #include "utility/utility.h"
 
@@ -22,7 +23,7 @@ QtIndexingDialog::QtIndexingDialog(QWidget* parent)
 	, m_percentLabel(nullptr)
 	, m_messageLabel(nullptr)
 	, m_filePathLabel(nullptr)
-	, m_errorLabel(nullptr)
+	, m_errorWidget(nullptr)
 	, m_fullRefreshCheckBox(nullptr)
 	, m_sizeHint(QSize(450, 450))
 	, m_callback([](DialogView::IndexingOptions){})
@@ -117,7 +118,7 @@ void QtIndexingDialog::setupIndexing()
 	addFilePathLabel(layout);
 
 	layout->addSpacing(12);
-	addErrorLabel(layout);
+	addErrorWidget(layout);
 
 	layout->addStretch();
 
@@ -134,6 +135,8 @@ void QtIndexingDialog::setupReport(
 	size_t indexedFileCount, size_t totalIndexedFileCount, size_t completedFileCount, size_t totalFileCount,
 	float time, bool interrupted)
 {
+	setType(DIALOG_REPORT);
+
 	QBoxLayout* layout = createLayout();
 
 	addTitle("Finished Indexing", layout);
@@ -151,7 +154,7 @@ void QtIndexingDialog::setupReport(
 	createMessageLabel(layout)->setText("Total Time:   " + QString::fromStdString(utility::timeToString(time)));
 
 	layout->addSpacing(12);
-	addErrorLabel(layout);
+	addErrorWidget(layout);
 
 	layout->addStretch();
 
@@ -251,7 +254,7 @@ void QtIndexingDialog::updateIndexingProgress(size_t fileCount, size_t totalFile
 
 void QtIndexingDialog::updateErrorCount(size_t errorCount, size_t fatalCount)
 {
-	if (m_errorLabel && errorCount)
+	if (m_errorWidget && errorCount)
 	{
 		QString str = QString::number(errorCount) + " Error";
 		if (errorCount > 1)
@@ -264,8 +267,10 @@ void QtIndexingDialog::updateErrorCount(size_t errorCount, size_t fatalCount)
 			str += " (" + QString::number(fatalCount) + " Fatal)";
 		}
 
-		m_errorLabel->setText(str);
-		m_errorLabel->show();
+		QPushButton* errorCount = m_errorWidget->findChild<QPushButton*>("errorCount");
+		errorCount->setText(str);
+
+		m_errorWidget->show();
 	}
 }
 
@@ -285,6 +290,10 @@ void QtIndexingDialog::handleNext()
 		options.fullRefresh = m_fullRefreshCheckBox && m_fullRefreshCheckBox->isChecked();
 		m_callback(options);
 	}
+	else if (m_type == DIALOG_REPORT)
+	{
+		MessageShowErrorHelpMessage().dispatch();
+	}
 
 	QtWindow::handleNext();
 }
@@ -395,17 +404,36 @@ void QtIndexingDialog::addFilePathLabel(QBoxLayout* layout)
 	layout->addWidget(m_filePathLabel);
 }
 
-void QtIndexingDialog::addErrorLabel(QBoxLayout* layout)
+void QtIndexingDialog::addErrorWidget(QBoxLayout* layout)
 {
-	m_errorLabel = new QPushButton();
-	m_errorLabel->setObjectName("errorCount");
-	m_errorLabel->setAttribute(Qt::WA_LayoutUsesWidgetRect); // fixes layouting on Mac
+	m_errorWidget = new QWidget();
+	QHBoxLayout* errorLayout = new QHBoxLayout(m_errorWidget);
+	errorLayout->setContentsMargins(0, 0, 0, 0);
+	errorLayout->setSpacing(5);
+
+	QPushButton* errorCount = new QPushButton();
+	errorCount->setObjectName("errorCount");
+	errorCount->setAttribute(Qt::WA_LayoutUsesWidgetRect); // fixes layouting on Mac
 
 	std::string text = ResourcePaths::getGuiPath().str() + "indexing_dialog/error.png";
-	m_errorLabel->setIcon(QPixmap(text.c_str()));
+	errorCount->setIcon(QPixmap(text.c_str()));
+	errorLayout->addWidget(errorCount);
 
-	layout->addWidget(m_errorLabel, 0, Qt::AlignRight);
-	m_errorLabel->hide();
+	QtHelpButton* helpButton = new QtHelpButton("aaa", "bbb");
+	helpButton->setColor(Qt::white);
+
+	helpButton->disconnect();
+	connect(helpButton, &QtHelpButton::clicked,
+		[]()
+		{
+			MessageShowErrorHelpMessage(true).dispatch();
+		}
+	);
+
+	errorLayout->addWidget(helpButton);
+
+	layout->addWidget(m_errorWidget, 0, Qt::AlignRight);
+	m_errorWidget->hide();
 }
 
 void QtIndexingDialog::addButtons(QBoxLayout* layout)

src/lib_gui/qt/window/QtIndexingDialog.h

@@ -21,7 +21,8 @@ public:
 		DIALOG_MESSAGE,
 		DIALOG_UNKNOWN_PROGRESS,
 		DIALOG_PROGRESS,
-		DIALOG_INDEXING
+		DIALOG_INDEXING,
+		DIALOG_REPORT
 	};
 
 	QtIndexingDialog(QWidget* parent = 0);
@@ -61,7 +62,7 @@ private:
 	void addMessageLabel(QBoxLayout* layout);
 	QLabel* createMessageLabel(QBoxLayout* layout);
 	void addFilePathLabel(QBoxLayout* layout);
-	void addErrorLabel(QBoxLayout* layout);
+	void addErrorWidget(QBoxLayout* layout);
 
 	void addButtons(QBoxLayout* layout);
 	void addFlag();
@@ -78,7 +79,7 @@ private:
 	QLabel* m_percentLabel;
 	QLabel* m_messageLabel;
 	QLabel* m_filePathLabel;
-	QPushButton* m_errorLabel;
+	QWidget* m_errorWidget;
 
 	// start indexing
 	QCheckBox* m_fullRefreshCheckBox;

src/lib_gui/qt/window/QtMainWindow.cpp

@@ -41,6 +41,7 @@
 #include "utility/messaging/type/MessageRefresh.h"
 #include "utility/messaging/type/MessageResetZoom.h"
 #include "utility/messaging/type/MessageSearch.h"
+#include "utility/messaging/type/MessageShowErrorHelpMessage.h"
 #include "utility/messaging/type/MessageUndo.h"
 #include "utility/messaging/type/MessageWindowClosed.h"
 #include "utility/messaging/type/MessageZoom.h"
@@ -433,6 +434,11 @@ void QtMainWindow::showKeyboardShortcuts()
 	keyboardShortcutWindow->setup();
 }
 
+void QtMainWindow::showErrorHelpMessage()
+{
+	MessageShowErrorHelpMessage(true).dispatch();
+}
+
 void QtMainWindow::showBugtracker()
 {
 	QDesktopServices::openUrl(QUrl("https://github.com/CoatiSoftware/SourcetrailBugTracker/issues"));
@@ -914,6 +920,7 @@ void QtMainWindow::setupHelpMenu()
 	menuBar()->addMenu(menu);
 
 	menu->addAction(tr("Keyboard Shortcuts"), this, &QtMainWindow::showKeyboardShortcuts);
+	menu->addAction(tr("Fixing Errors"), this, &QtMainWindow::showErrorHelpMessage);
 	menu->addAction(tr("Documentation"), this, &QtMainWindow::showDocumentation);
 	menu->addAction(tr("Bug Tracker"), this, &QtMainWindow::showBugtracker);
 

src/lib_gui/qt/window/QtMainWindow.h

@@ -95,6 +95,7 @@ public slots:
 	void showBugtracker();
 	void showDocumentation();
 	void showKeyboardShortcuts();
+	void showErrorHelpMessage();
 	void showEula(bool forceAccept = false);
 	void acceptedEula();
 	void showLicenses();