From 85b1c42cd150967b2e025146e71ca1fb96b3a09d Mon Sep 17 00:00:00 2001
From: Kacper Donat <kadet1090@gmail.com>
Date: Wed, 4 Jun 2025 11:25:38 +0200
Subject: [PATCH] Gui: Add guidelines for input hints

---
 src/Gui/InputHint.h | 43 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/src/Gui/InputHint.h b/src/Gui/InputHint.h
index 0d0a9111e5..bcd38dcc3a 100644
--- a/src/Gui/InputHint.h
+++ b/src/Gui/InputHint.h
@@ -33,6 +33,36 @@
 
 namespace Gui
 {
+
+/**
+ * @brief Representation of one input hint.
+ *
+ * Each input is essentially a short message defining action with reference to inputs that will
+ * trigger that action.
+ *
+ * For example,
+ * @code{c++}
+ * using enum InputHint::UserInput;
+ *
+ * // simple example of hint
+ * InputHint selectPointHint {
+ *     .message = QWidget::tr("%1 select point"),
+ *     .sequences = { MouseLeft }
+ * }
+ *
+ * // multiple sequences are also allowed in one hint
+ * InputHint lockAxisHint {
+ *     .message = QWidget::tr("%1, %2 or %3 lock X, Y or Z axis"),
+ *     .sequences = { KeyX, KeyY, KeyZ }
+ * }
+ *
+ * // hints can also use sequences consisting of multiple keys
+ * InputHint exitProgramHint {
+ *     .message = QWidget::tr("%1 exit program"),
+ *     .sequences = { {KeyAlt, KeyF4} }
+ * }
+ * @endcode
+ */
 struct InputHint
 {
     enum class UserInput
@@ -225,7 +255,20 @@ struct InputHint
         {}
     };
 
+    /**
+     * @brief Message associated with the hint.
+     *
+     * The message should confirm to rules stated in the documentation of the InputHint class.
+     * Message can contain placeholders like %1, %2 etc. that will then be replaced with graphical
+     * key representation from sequences field.
+     *
+     * @see https://freecad.github.io/DevelopersHandbook/designguide/input-hints.html
+     */
     QString message;
+
+    /**
+     * @brief List of sequences to be substituted.
+     */
     std::list<InputSequence> sequences;
 };