Update documentation for World and some other world-related entities

engine/world/Camera.h

@@ -49,6 +49,8 @@ struct Unit;
 class SceneGraph;
 
 /// Represents the point of view into the game world.
+///
+/// @ingroup World
 struct Camera
 {
 							Camera(SceneGraph& sg, int32_t node);

engine/world/SceneGraph.h

@@ -37,6 +37,8 @@ namespace crown
 
 class Allocator;
 
+///
+/// @ingroup World
 struct SceneGraph
 {
 					SceneGraph(Allocator& a, uint32_t index);

engine/world/SceneGraphManager.h

@@ -34,6 +34,8 @@ namespace crown
 class SceneGraph;
 
 /// Manages a collection of scene graphs.
+///
+/// @ingroup World
 class SceneGraphManager
 {
 public:

engine/world/Unit.h

@@ -73,6 +73,9 @@ struct Sprite;
 struct Material;
 struct UnitResource;
 
+/// Represents a game entity.
+///
+/// @ingroup World
 struct Unit
 {
 						Unit(World& w, const ResourceId id, const UnitResource* ur, const Matrix4x4& pose);

engine/world/World.h

@@ -53,6 +53,11 @@ struct Quaternion;
 struct PhysicsResource;
 struct DebugLine;
 
+/// @defgroup World World
+
+/// Represents a game world.
+///
+/// @ingroup World
 class World
 {
 public:
@@ -62,33 +67,58 @@ public:
 	WorldId								id() const;
 	void								set_id(WorldId id);
 
-	UnitId								spawn_unit(const char* name, const Vector3& pos = vector3::ZERO, const Quaternion& rot = quaternion::IDENTITY);
+	/// Spawns a new instance of the unit @a name at the given @a position and @a rotation.
+	UnitId								spawn_unit(const char* name, const Vector3& position = vector3::ZERO, const Quaternion& rotation = quaternion::IDENTITY);
 	UnitId								spawn_unit(const ResourceId id, UnitResource* ur, const Vector3& pos, const Quaternion& rot);
 
+	/// Destroys the unit with the given @a id.
 	void								destroy_unit(UnitId id);
 	void								reload_units(UnitResource* old_ur, UnitResource* new_ur);
 
+	/// Returns the number of units in the world.
 	uint32_t							num_units() const;
 
+	/// Links the unit @a child to the @a node of the unit @a parent.
+	/// After this call, @a child will follow the @a parent unit.
 	void								link_unit(UnitId child, UnitId parent, int32_t node);
+
+	/// Unlinks the unit @a unit from its parent if it has any.
 	void								unlink_unit(UnitId unit);
 
 	Unit*								lookup_unit(UnitId unit);
 	Camera*								lookup_camera(CameraId camera);
 
+	/// Updates all units and sub-systems with the given @a dt delta time.
 	void								update(float dt);
+
+	/// Renders the world form the point of view of the given @a camera.
 	void								render(Camera* camera);
 
 	CameraId							create_camera(SceneGraph& sg, int32_t node);
 	void								destroy_camera(CameraId id);
 
-	SoundInstanceId						play_sound(const char* name, bool loop = false, float volume = 1.0f, const Vector3& pos = vector3::ZERO, float range = 50.0f);
-	void								stop_sound(SoundInstanceId sound);
-	void								link_sound(SoundInstanceId sound, Unit* unit, int32_t node);
+	/// Plays the sound with the given @æ name at the given @a position, with the given
+	/// @a volume and @a range. @a loop controls whether the sound must loop or not.
+	SoundInstanceId						play_sound(const char* name, bool loop = false, float volume = 1.0f, const Vector3& position = vector3::ZERO, float range = 50.0f);
+
+	/// Stops the sound with the given @a id.
+	void								stop_sound(SoundInstanceId id);
+
+	/// Links the sound @a if to the @a node of the given @æ unit.
+	/// After this call, the sound @a id will follow the unit @æ unit.
+	void								link_sound(SoundInstanceId id, Unit* unit, int32_t node);
+
+	/// Sets the @a pose of the listener.
 	void								set_listener_pose(const Matrix4x4& pose);
-	void								set_sound_position(SoundInstanceId sound, const Vector3& pos);
-	void								set_sound_range(SoundInstanceId sound, float range);
-	void								set_sound_volume(SoundInstanceId sound, float vol);
+
+	/// Sets the @a position of the sound @a id.
+	void								set_sound_position(SoundInstanceId id, const Vector3& position);
+
+	/// Sets the @a range of the sound @a id.
+	void								set_sound_range(SoundInstanceId id, float range);
+
+	/// Sets the @a volume of the sound @a id.
+	void								set_sound_volume(SoundInstanceId id, float volume);
 
 	GuiId								create_window_gui(const char* name);
 	GuiId								create_world_gui(const Matrix4x4 pose, const uint32_t width, const uint32_t height);

engine/world/WorldManager.h

@@ -36,6 +36,8 @@ typedef Id WorldId;
 class World;
 
 /// Manages a number of worlds.
+///
+/// @ingroup World
 class WorldManager
 {
 public: