update Open Source Docs from Roblox internal teams

content/en-us/reference/engine/classes/CollectionService.yaml

@@ -3,16 +3,16 @@ type: class
 category: Utility
 memory_category: Instances
 summary: |
-  A service which manages object collections using assigned tags.
+  A service which manages instance collections using assigned tags.
 description: |
-  `Class.CollectionService` manages groups (collections) of instances with
-  **tags**. Tags are sets of strings applied to objects that replicate from the
-  server to the client. They are also serialized when places are saved.
+  `CollectionService` manages groups (collections) of instances with **tags**.
+  Tags are sets of strings applied to instances that replicate from the server
+  to the client. They are also serialized when places are saved.
 
-  The primary use of `Class.CollectionService` is to register instances with
-  specific tags that you can use to extend their behavior. If you find yourself
-  adding the same script to many different objects, perhaps a script that uses
-  `Class.CollectionService` would be better.
+  The primary use of `CollectionService` is to register instances with specific
+  tags that you can use to extend their behavior. If you find yourself adding
+  the same script to many different instances, a script that uses
+  `CollectionService` may be better.
 
   Tags can be added or removed through this class' methods such as
   `Class.CollectionService:AddTag()|AddTag()` or
@@ -22,12 +22,12 @@ description: |
   properties, or through the built‑in
   [Tag Editor](../../../studio/view-tab.md#windows-and-tools) tool.
 
-  #### Replication
+  ##### Replication
 
-  When tags replicate, **all tags on an object replicate at the same time**.
-  Therefore, if you set a tag on an object from the client then add/remove a
-  **different** tag on the same object from the server, the client's local tags
-  on the object are overwritten. In
+  When tags replicate, **all tags on an instance replicate at the same time**.
+  Therefore, if you set a tag on an instance from the client then add/remove a
+  **different** tag on the same instance from the server, the client's local
+  tags on the instance are overwritten. In
   `Class.Workspace.StreamingEnabled|StreamingEnabled` places, instances can be
   unloaded as they leave the client's streamed area. If such an instance
   re-enters the streamed area, properties and tags will be re-synchronized from
@@ -46,10 +46,11 @@ methods:
     summary: |
       Applies a tag to an `Class.Instance`.
     description: |
-      AddTag will apply a tag to an `Class.Instance`, doing nothing if the tag
-      is already applied to the instance. Successfully adding a tag will fire a
-      signal created by `Class.CollectionService:GetInstanceAddedSignal()` with
-      the given tag.
+      This method applies a tag to an `Class.Instance`, doing nothing if the tag
+      is already applied to that instance. Successfully adding a tag will fire a
+      signal created by
+      `Class.CollectionService:GetInstanceAddedSignal()|GetInstanceAddedSignal()`
+      with the given tag.
 
       ##### Warnings
 
@@ -61,9 +62,9 @@ methods:
         give the tag its functionality, for example event connections or tables.
         To prevent memory leaks, it's a good idea to clean these up (disconnect,
         set to `nil`, etc.) when no longer needed for a tag. Do this when
-        calling `Class.CollectionService:RemoveTag()`, calling
+        calling `Class.CollectionService:RemoveTag()|RemoveTag()`, calling
         `Class.Instance:Destroy()` or in a function connected to a signal
-        returned by `Class.CollectionService:GetInstanceRemovedSignal()`.
+        returned by `Class.CollectionService:GetInstanceRemovedSignal()|GetInstanceRemovedSignal()`.
     code_samples:
     parameters:
       - name: instance
@@ -85,8 +86,10 @@ methods:
     capabilities: []
     writeCapabilities: []
   - name: CollectionService:GetAllTags
-    summary: ''
-    description: ''
+    summary: |
+      Returns an array of all tags in the experience.
+    description: |
+      Returns an array of all tags in the experience.
     code_samples: []
     parameters: []
     returns:
@@ -128,23 +131,27 @@ methods:
     writeCapabilities: []
   - name: CollectionService:GetInstanceAddedSignal
     summary: |
-      Returns a signal that fires when a given tag is added to an object.
+      Returns a signal that fires when a given tag is added to an instance.
     description: |
-      GetInstanceAdded is given a tag (a string) and returns a signal which
-      fires under two conditions:
+      Given a tag (string), this method returns a signal which fires under two
+      conditions:
+
+      - The tag is assigned to an instance within the `Class.DataModel` using
+      `Class.CollectionService:AddTag()` or `Class.Instance:AddTag()`.
 
-      - The tag is assigned to an instance within the `Class.DataModel` (game)
-        using `Class.CollectionService:AddTag()` or `Class.Instance:AddTag()`.
       - An instance with the given tag is added as a descendant of the
-        `Class.DataModel`, e.g. by setting `Class.Instance.Parent` or similar.
+      `Class.DataModel`, for example by setting `Class.Instance.Parent` or
+      similar.
 
       Subsequent calls to this method with the same tag return the same signal
-      object. Consider also calling `Class.CollectionService:GetTagged()` to get
-      a list of objects that already have a tag (and thus won't fire the event
-      if they already are in the `Class.DataModel`).
+      object. Consider also calling
+      `Class.CollectionService:GetTagged()|GetTagged()` to get a list of
+      instances that already have a tag (and thus won't fire the event if they
+      already are in the `Class.DataModel`).
 
-      See also `Class.CollectionService:GetInstanceRemovedSignal()`, which
-      returns an event that fires under similar conditions.
+      See also
+      `Class.CollectionService:GetInstanceRemovedSignal()|GetInstanceRemovedSignal()`
+      which returns an event that fires under similar conditions.
     code_samples:
       - Deadly-Bricks-using-CollectionService
     parameters:
@@ -167,22 +174,22 @@ methods:
     summary: |
       Returns a signal that fires when a given tag is removed from an instance.
     description: |
-      GetInstanceRemoved is given a tag (a string) and returns a signal which
-      fires under two conditions:
+      Given a tag (string), this method returns a signal which fires under two
+      conditions:
+
+      - The tag is removed from an instance within the `Class.DataModel` using
+      `Class.CollectionService:RemoveTag()` or `Class.Instance:RemoveTag()`.
 
-      - The tag is removed from an instance within the `Class.DataModel` (game)
-        using `Class.CollectionService:RemoveTag()` or
-        `Class.Instance:RemoveTag()`.
       - An instance with the given tag is removed as a descendant of the
-        `Class.DataModel`, e.g. by un-setting `Class.Instance.Parent` or
-        similar.
+      `Class.DataModel`, for example by un‑setting `Class.Instance.Parent` or similar.
 
       Subsequent calls to this method with the same tag return the same signal
-      object. The signal is useful for cleaning up resources used by objects
+      object. The signal is useful for cleaning up resources used by instances
       that once had tags, such as disconnecting connections.
 
-      See also `Class.CollectionService:GetInstanceAddedSignal()`, which returns
-      an event that fires under similar conditions.
+      See also
+      `Class.CollectionService:GetInstanceAddedSignal()|GetInstanceAddedSignal()`
+      which returns an event that fires under similar conditions.
     code_samples:
       - Deadly-Bricks-using-CollectionService
     parameters:
@@ -203,24 +210,22 @@ methods:
     writeCapabilities: []
   - name: CollectionService:GetTagged
     summary: |
-      Returns an array of objects in the game with a given tag.
+      Returns an array of instances in the game with a given tag.
     description: |
-      GetTagged returns an array of objects with a given tag which are
-      descendants of the `Class.DataModel` (`game`). Such tags have been added
-      using `Class.CollectionService:AddTag()`, and removing a tag using
-      `Class.CollectionService:RemoveTag()` will ensure this method does not
-      return them. Although the name of this method is past-tense, this method
-      only returns objects **presently** tagged with the given tag. It will not
-      return objects that once had a tag but no longer have it.
+      This method returns an array of instances with a given tag which are
+      descendants of the `Class.DataModel`. Removing a tag using
+      `Class.CollectionService:RemoveTag()` or `Class.Instance:RemoveTag()`
+      ensures this method does not return them.
 
-      If you want to detect all objects with a tag, both present and future, use
-      this method to iterate over objects while also making a connection to a
-      signal returned by `Class.CollectionService.GetInstanceAddedSignal`.
+      If you want to detect all instances with a tag, both present **and**
+      future, use this method to iterate over instances while also making a
+      connection to a signal returned by
+      `Class.CollectionService:GetInstanceAddedSignal()|GetInstanceAddedSignal()`.
 
-      This method does not guarantee any ordering of the returned objects.
-      Additionally, it is possible that objects can have the given tag assigned
-      to them, but not be a descendant of the `Class.DataModel`, i.e. its parent
-      is nil. This method will not return such objects.
+      This method does not guarantee any ordering of the returned instances.
+      Additionally, it's possible that instances can have the given tag assigned
+      to them but not be a descendant of the `Class.DataModel`, for example its
+      parent is `nil`; this method will not return such instances.
     code_samples:
       - Deadly-Bricks-using-CollectionService
     parameters:
@@ -241,36 +246,27 @@ methods:
     writeCapabilities: []
   - name: CollectionService:GetTags
     summary: |
-      Gets an array of all tags applied to a given object.
+      Gets an array of all tags applied to a given instance.
     description: |
-      GetTags is given an instance and returns an array of strings, which are
-      the tags applied to the given object.
+      Given an `Class.Instance`, this method returns an array of strings which
+      are the tags applied to the instance.
 
-      ```
-      local CollectionService = game:GetService("CollectionService")
-      local Workspace = game:GetService("Workspace")
-
-      local object = Workspace.Model
-      local tags = CollectionService:GetTags(object)
-      print("The object " .. object:GetFullName() .. " has tags: " .. table.concat(tags, ", "))
-      ```
-
-      This method is useful when you want to do something with multiple tags at
-      once on an object. However, it would be inefficient to use this method to
-      check for the existence of a single tag. For this, use
-      `Class.CollectionService:HasTag()` to check for a single tag.
+      This method is useful when you want to do something with multiple instance
+      tags at once, but it's inefficient to check for the existence of a single
+      tag. For this, use `Class.CollectionService:HasTag()|HasTag()` to check
+      for a single tag.
     code_samples:
       - Using-Tags-and-CollectionService
     parameters:
       - name: instance
         type: Instance
         default:
         summary: |
-          The object whose tags should be returned.
+          The instance whose tags should be returned.
     returns:
       - type: Array
         summary: |
-          An array of strings which are the tags applied to the given object.
+          An array of strings which are the tags applied to the given instance.
     tags:
       - CustomLuaState
     deprecation_message: ''
@@ -280,18 +276,13 @@ methods:
     writeCapabilities: []
   - name: CollectionService:HasTag
     summary: |
-      Check whether an object has a given tag.
+      Check whether an instance has a given tag.
     description: |
-      HasTag returns whether a given object has a tag.
-
-      - Using `Class.CollectionService:AddTag()` to add the tag will cause this
-        method to return true.
-      - Using `Class.CollectionService:RemoveTag()` to remove the tag will cause
-        this method to return false.
+      This method returns whether a given `Class.Instance` has a tag.
 
       By extension, any tags returned by a call to
-      `Class.CollectionService:GetTags()` on an object will return true when
-      used with this method.
+      `Class.CollectionService:GetTags()|GetTags()` on an instance will return
+      `true` when used with this method.
     code_samples:
       - Using-Tags-and-CollectionService
     parameters:
@@ -320,15 +311,15 @@ methods:
     summary: |
       Removes a tag from an instance.
     description: |
-      RemoveTag will remove a tag from an instance. This method will not throw
-      an error if the object did not have the tag in the first place.
-      Successfully removing a tag will fire a signal created by
-      `Class.CollectionService:GetInstanceRemovedSignal()` with the given tag.
+      This method removes a tag from an instance. Successfully removing a tag
+      will fire a signal created by
+      `Class.CollectionService:GetInstanceRemovedSignal()|GetInstanceRemovedSignal()`
+      with the given tag.
 
-      When removing a tag, it is common that some resources are used to give the
-      tag its functionality, e.g. event connections or tables. To prevent memory
-      leaks, it is a good idea to clean these up (disconnect, set to nil, etc)
-      when no longer needed for a tag.
+      When removing a tag, it's common that some resources are used to give the
+      tag its functionality, for example event connections or tables. To prevent
+      memory leaks, it's a good idea to clean these up (disconnect, set to
+      `nil`, etc.) when no longer needed for a tag.
     code_samples:
       - Using-Tags-and-CollectionService
     parameters:
@@ -405,11 +396,11 @@ events:
     writeCapabilities: []
   - name: CollectionService.TagAdded
     summary: |
-      Fires when a tag is added to an object and the added tag is the only
+      Fires when a tag is added to an instance and the added tag is the only
       occurrence of that tag in the place.
     description: |
-      This event fires when a tag is added to an object and the added tag is the
-      only occurrence of that tag in the place.
+      This event fires when a tag is added to an instance and the added tag is
+      the only occurrence of that tag in the place.
     code_samples: []
     parameters:
       - name: tag
@@ -424,11 +415,11 @@ events:
     writeCapabilities: []
   - name: CollectionService.TagRemoved
     summary: |
-      Fires when a tag is removed from an object and the removed tag is no
+      Fires when a tag is removed from an instance and the removed tag is no
       longer used anywhere in the place.
     description: |
-      This event fires when a tag is removed from an object and the removed tag
-      is no longer used anywhere in the place.
+      This event fires when a tag is removed from an instance and the removed
+      tag is no longer used anywhere in the place.
     code_samples: []
     parameters:
       - name: tag