chore: doxygen documentation for player

player.hpp

@@ -5,21 +5,31 @@
 #include <optional>
 #include <godot_cpp/variant/transform3d.hpp>
 
-namespace godot { class Node; }
-
 namespace gd = godot;
 
+namespace godot { class Node; }
+
 namespace utils {
 class PlayerInput;
 
+/*! Interface required for player nodes.
+ *
+ * Use multiple inheritance and implement IPlayer to make a regular node usable as a player with GameRoot3D.
+ */
 class IPlayer {
 friend class GameRoot3D;
 public:
+    /*! Called by GameRoot3D when this player is instantiated or assigned a new PlayerInput.
+     *
+     * Use PlayerInput::listen_to to register input callbacks. There's no need to keep the input pointer around. As the instance is managed by the GameRoot3D.
+     */
     virtual void setup_player_input(PlayerInput *input) = 0;
+    //! Convert IPlayer instance to node.
     virtual gd::Node *to_node() = 0;
+    //! Spawn the player at a given transform, usually the global transform of a SpawnPoint3D.
     virtual void spawn_at_position(gd::Transform3D const &at) = 0;
 
-    uint32_t get_player_id();
+    uint32_t get_player_id(); //!< Returns the player id assigned to this instance.
 
 private:
     std::optional<uint32_t> player_id{std::nullopt};