Add documentation for ItemMapperSystem etc. (#9998)

Content.Server/Storage/EntitySystems/ItemMapperSystem.cs

@@ -6,6 +6,7 @@ using Robust.Shared.Containers;
 
 namespace Content.Server.Storage.EntitySystems
 {
+    /// <inheritdoc/>
     [UsedImplicitly]
     public sealed class ItemMapperSystem : SharedItemMapperSystem
     {

Content.Shared/Storage/Components/ItemMapperComponent.cs

@@ -3,6 +3,55 @@ using Robust.Shared.Serialization;
 
 namespace Content.Shared.Storage.Components
 {
+    /// <summary>
+    /// <para><c>ItemMapperComponent</c> is a <see cref="Component"/> that maps string labels to an <see cref="Content.Shared.Whitelist.EntityWhitelist"/> of elements. Useful primarily  for visualization.</para>
+    /// <para>
+    /// To define a mapping, create a <c>mapLayers</c> map in configuration <c>ItemMapper</c> component and with <see cref="MapLayers"/> mapping.
+    /// Each map layer maps layer name to an <see cref="Content.Shared.Whitelist.EntityWhitelist"/>, plus special modifiers for min and max item count.
+    /// Min and max count are useful when you need to visualize a certain number of items, for example, to display one, two, three, or more items.
+    /// </para>
+    /// <para>
+    /// If you need a more straightforward way to change appearance where only variable is how many items, rather than which items
+    /// and how many, see <see cref="ItemCounterComponent"/>
+    /// </para>
+    /// <para>
+    /// For a contrived example, create a tool-belt with a Power drill slot and two light bulb slots.
+    /// To use this for visualization, we need <see cref="AppearanceComponent"/> a or VisualizerSystem, e.g.
+    /// <code>
+    ///   - type: Appearance
+    ///      visuals:
+    ///      - type: MappedItemVisualizer
+    /// </code>
+    /// To map <c>Powerdrill</c> <b><see cref="Content.Shared.Tag.TagComponent"/></b> to the given example, we need the following code.
+    /// <code>
+    /// - type: ItemMapper
+    ///   mapLayers:
+    ///     drill:
+    ///       whitelist:
+    ///         tags:
+    ///         - Powerdrill
+    /// #... to be continued
+    /// </code>
+    /// To map <c>Lightbulb</c> <b><see cref="Component"/></b> (not tag) to two different layers (for one and two light bulbs, respectively)
+    /// <code>
+    /// #... to be continued
+    ///     lightbulb1:
+    ///       minCount: 1
+    ///       whitelist:
+    ///         component:
+    ///         - Lightbulb
+    ///     lightbulb2:
+    ///       minCount: 2
+    ///       whitelist:
+    ///         component:
+    ///         - Lightbulb
+    /// </code>
+    /// The min count will ensure that <c>lightbulb1</c> layer is only displayed when one or more light bulbs are in the belt.
+    /// And <c>lightbulb2</c> layer will only be shown when two or more light bulbs are inserted.
+    /// </para>
+    /// <seealso cref="Content.Shared.Whitelist.EntityWhitelist"/>
+    /// <seealso cref="Content.Shared.Storage.Components.SharedMapLayerData"/>
+    /// </summary>
     [RegisterComponent]
     [Access(typeof(SharedItemMapperSystem))]
     public sealed class ItemMapperComponent : Component, ISerializationHooks

Content.Shared/Storage/EntitySystems/SharedItemMapperSystem.cs

@@ -4,6 +4,11 @@ using Robust.Shared.Containers;
 
 namespace Content.Shared.Storage.EntitySystems
 {
+    /// <summary>
+    /// <c>ItemMapperSystem</c> is a system that on each initialization, insertion, removal of an entity from
+    /// given <see cref="ItemMapperComponent"/> (with appropriate storage attached) will check each stored item to see
+    /// if its tags/component, and overall quantity match <see cref="ItemMapperComponent.MapLayers"/>.
+    /// </summary>
     [UsedImplicitly]
     public abstract class SharedItemMapperSystem : EntitySystem
     {
@@ -45,6 +50,17 @@ namespace Content.Shared.Storage.EntitySystems
             }
         }
 
+        /// <summary>
+        /// Method that iterates over storage of the entity in <paramref name="msg"/> and sets <paramref name="containedLayers"/> according to
+        /// <paramref name="itemMapper"/> definition. It will have O(n*m) time behavior (n - number of entities in container, and m - number of
+        /// definitions in <paramref name="containedLayers"/>.
+        /// </summary>
+        /// <param name="msg">event with EntityUid used to search the storage</param>
+        /// <param name="itemMapper">component that contains definition used to map <see cref="Content.Shared.Whitelist.EntityWhitelist">whitelist</see> in
+        /// <c>mapLayers</c> to string.
+        /// </param>
+        /// <param name="containedLayers">list of <paramref name="itemMapper"/> layers that should be visible</param>
+        /// <returns>false if <c>msg.Container.Owner</c> is not a storage, true otherwise.</returns>
         protected abstract bool TryGetLayers(ContainerModifiedMessage msg,
             ItemMapperComponent itemMapper,
             out IReadOnlyList<string> containedLayers);