From 6c4c7ec75103b172fb007550cf8368158413aac4 Mon Sep 17 00:00:00 2001
From: Tobias Hunger <tobias.hunger@qt.io>
Date: Thu, 23 Apr 2020 11:05:16 +0200
Subject: [PATCH] ProjectExplorer: Document how ProjectExplorer::BuildSystem
 interacts

Document how ProjectExplorer::BuildSystem interacts with its
surrounding in a sequence diagram stored in buildsystem.md.

Change-Id: I1419ac63af73e382440f42a168bb103dec8d4b0c
Reviewed-by: Eike Ziller <eike.ziller@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
---
 src/plugins/projectexplorer/buildsystem.md | 34 ++++++++++++++++++++++
 1 file changed, 34 insertions(+)
 create mode 100644 src/plugins/projectexplorer/buildsystem.md

diff --git a/src/plugins/projectexplorer/buildsystem.md b/src/plugins/projectexplorer/buildsystem.md
new file mode 100644
index 00000000000..86c279252d4
--- /dev/null
+++ b/src/plugins/projectexplorer/buildsystem.md
@@ -0,0 +1,34 @@
+# BuildSystem
+
+This is a sequence diagram of how ProjectExplorer::BuildSystem interacts with
+its implementations:
+
+```mermaid
+sequenceDiagram
+    User ->> BuildSystemImpl: provide data and ask for parse (impl. defined!)
+    BuildSystemImpl ->> BuildSystem: call requestParse() or requestDelayedParse()
+    activate BuildSystem
+    BuildSystem ->> BuildSystem: m_delayedParsingTimer sends timeout()
+    BuildSystem ->> BuildSystemImpl: call triggerParsing()
+    deactivate BuildSystem
+    activate BuildSystemImpl
+    BuildSystemImpl ->> BuildSystem: call guardParsingRun()
+    activate BuildSystem
+    BuildSystem ->> ParseGuard: Construct
+    activate ParseGuard
+    ParseGuard ->> BuildSystem: call emitParsingStarted
+    BuildSystem ->> User: signal parsingStarted()
+    BuildSystem ->> BuildSystemImpl: Hand over ParseGuard
+    deactivate BuildSystem
+    BuildSystemImpl ->> BuildSystemImpl: Do parsing
+    opt Report Success
+    BuildSystemImpl ->> ParseGuard: markAsSuccess()
+    end
+    BuildSystemImpl ->> ParseGuard: Destruct
+    ParseGuard ->> BuildSystem: emitParsingFinished()
+    activate BuildSystem
+    BuildSystem ->> User: Signal ParsingFinished(...)
+    deactivate BuildSystem
+    deactivate ParseGuard
+    deactivate BuildSystemImpl
+```