diff --git a/doc/lua_api.txt b/doc/lua_api.txt
index ba4d6312c..4ef67261a 100644
--- a/doc/lua_api.txt
+++ b/doc/lua_api.txt
@@ -6938,7 +6938,11 @@ Player properties need to be saved manually.
         -- in mods.
 
         nametag = "",
-        -- By default empty, for players their name is shown if empty
+        -- The name to display on the head of the object. By default empty.
+        -- If the object is a player, a nil or empty nametag is replaced by the player's name.
+        -- For all other objects, a nil or empty string removes the nametag.
+        -- To hide a nametag, set its color alpha to zero. That will disable it entirely.
+
 
         nametag_color = <ColorSpec>,
         -- Sets color of nametag