From f58c71016ba4793e7dfa8aa7a8b65655c5042fb3 Mon Sep 17 00:00:00 2001
From: copygirl <copygirl@mcft.net>
Date: Wed, 13 Sep 2023 19:30:17 +0200
Subject: [PATCH] Some doc changes regarding ownership

---
 src/entity.zig | 27 +++++++++++++++++++--------
 1 file changed, 19 insertions(+), 8 deletions(-)

diff --git a/src/entity.zig b/src/entity.zig
index 1655c6c..2a05c77 100644
--- a/src/entity.zig
+++ b/src/entity.zig
@@ -95,6 +95,9 @@ pub fn Entity(comptime ctx: anytype) type {
             var name = config.name;
             var scope = if (config.parent) |p| p.raw else null;
 
+            // TODO: Use an allocator that's well-fitted for super short-lived allocations.
+            const alloc = flecs.allocator;
+
             if (config.path) |path| {
                 if (path.absolute) {
                     // Specifying parent with an absolute path is invalid.
@@ -128,9 +131,8 @@ pub fn Entity(comptime ctx: anytype) type {
                             scope = found;
                         },
                         .name => |n| {
-                            // TODO: Use an allocator that's well-fitted for super short-lived allocations.
-                            const nameZ = try flecs.allocator.dupeZ(u8, n);
-                            defer flecs.allocator.free(nameZ);
+                            const nameZ = try alloc.dupeZ(u8, n);
+                            defer alloc.free(nameZ);
                             const found = c.ecs_lookup_child(world.raw, parent, nameZ.ptr);
                             if (found == 0) {
                                 var desc = std.mem.zeroInit(c.ecs_entity_desc_t, .{ .sep = "".ptr, .name = nameZ.ptr });
@@ -148,11 +150,10 @@ pub fn Entity(comptime ctx: anytype) type {
             const previous = if (scope) |s| world.setScope(s) else null;
             defer _ = if (scope != null) world.setScope(previous);
 
-            // TODO: Use an allocator that's well-fitted for super short-lived allocations.
-            const nameZ = if (name) |n| try flecs.allocator.dupeZ(u8, n) else null;
-            defer if (nameZ) |n| flecs.allocator.free(n);
-            const symbolZ = if (config.symbol) |s| try flecs.allocator.dupeZ(u8, s) else null;
-            defer if (symbolZ) |s| flecs.allocator.free(s);
+            const nameZ = if (name) |n| try alloc.dupeZ(u8, n) else null;
+            defer if (nameZ) |n| alloc.free(n);
+            const symbolZ = if (config.symbol) |s| try alloc.dupeZ(u8, s) else null;
+            defer if (symbolZ) |s| alloc.free(s);
 
             var desc = std.mem.zeroInit(c.ecs_entity_desc_t, .{
                 .sep = "".ptr, // Disable tokenization.
@@ -231,23 +232,33 @@ pub fn Entity(comptime ctx: anytype) type {
         }
 
         /// Gets the name of this `Entity`, or `null` if none.
+        ///
+        /// The returned string is owned by Flecs and may only be valid while
+        /// the entity is alive and its name doesn't change.
         pub fn getName(self: Self) ?[:0]const u8 {
             const result = c.ecs_get_name(self.world.raw, self.raw);
             return std.mem.sliceTo(result, 0);
         }
 
         /// Gets the symbol of this `Entity`, or `null` if none.
+        ///
+        /// The returned string is owned by Flecs and may only be valid while
+        /// the entity is alive and its symbol doesn't change.
         pub fn getSymbol(self: Self) ?[:0]const u8 {
             const result = c.ecs_get_symbol(self.world.raw, self.raw);
             return std.mem.sliceTo(result, 0);
         }
 
         /// Sets the name of this `Entity` to the specified value, if any.
+        ///
+        /// Flecs does not take ownership of the provided value.
         pub fn setName(self: Self, value: ?[*:0]const u8) void {
             _ = c.ecs_set_name(self.world.raw, self.raw, value);
         }
 
         /// Sets the symbol of this `Entity` to the specified value, if any.
+        ///
+        /// Flecs does not take ownership of the provided value.
         pub fn setSymbol(self: Self, value: ?[*:0]const u8) void {
             _ = c.ecs_set_symbol(self.world.raw, self.raw, value);
         }