From 88b58cf23d1189fc37f8edb09b1cf031ca89c049 Mon Sep 17 00:00:00 2001
From: Michele Caini <michele.caini@gmail.com>
Date: Thu, 27 May 2021 11:15:44 +0200
Subject: [PATCH] doc: added a note about tombstones

---
 docs/md/entity.md | 44 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/docs/md/entity.md b/docs/md/entity.md
index 311b47bd5..55ba12010 100644
--- a/docs/md/entity.md
+++ b/docs/md/entity.md
@@ -19,6 +19,7 @@
   * [Sorting: is it possible?](#sorting-is-it-possible)
   * [Helpers](#helpers)
     * [Null entity](#null-entity)
+    * [Tombstone](#tombstone)
     * [To entity](#to-entity)
     * [Dependencies](#dependencies)
     * [Invoke](#invoke)
@@ -621,11 +622,54 @@ const auto entity = registry.create();
 const bool null = (entity == entt::null);
 ```
 
+As for its integral form, the null entity only affects the entity part of an
+identifier and is instead completely transparent to its version.
+
 Be aware that `entt::null` and entity 0 aren't the same thing. Likewise, a zero
 initialized entity isn't the same as `entt::null`. Therefore, although
 `entt::entity{}` is in some sense an alias for entity 0, none of them can be
 used to create a null entity.
 
+### Tombstone
+
+In addition to the null entity, `EnTT` also models the concept of _tombstone_
+with the `entt::tombstone` variable.<br/>
+Once created, the integral form of the two values is the same, although they
+affect different parts of an identifier. In fact, the tombstone uses only the
+version part and is completely transparent to the entity part.
+
+Also in this case, the following expression always returns false:
+
+```cpp
+registry.valid(entt::tombstone);
+```
+
+Moreover, users cannot set set the tombstone version when deleting an entity:
+
+```
+registry.destroy(entity, entt::tombstone);
+```
+
+In this case, a different version number is implicitly generated.<br/>
+The type of a tombstone is internal and can change at any time. However, there
+exist implicit conversions from a tombstone to identifiers of any allowed type:
+
+```cpp
+entt::entity null = entt::tombstone;
+```
+
+Similarly, the tombstone can be compared to any other identifier:
+
+```cpp
+const auto entity = registry.create();
+const bool tombstone = (entity == entt::tombstone);
+```
+
+Be aware that `entt::tombstone` and entity 0 aren't the same thing. Likewise, a
+zero initialized entity isn't the same as `entt::tombstone`. Therefore, although
+`entt::entity{}` is in some sense an alias for entity 0, none of them can be
+used to create tombstones.
+
 ### To entity
 
 Sometimes it's useful to get the entity from a component instance.<br/>