Document all analyzer attributes. (space-wizards#6467)

Author: moonheart08

Robust.Shared/Analyzers/AccessAttribute.cs

@@ -6,10 +6,57 @@ namespace Robust.Shared.Analyzers.Implementation;
 namespace Robust.Shared.Analyzers;
 #endif
 
+/// <summary>
+/// <para>
+///     Access is a way to describe how other classes are allowed to use a field in more precise terms than "can use"
+///     and "cannot use". Think of it like friend classes from C++.
+/// </para>
+/// <para>
+///     Access controls field, method, and property usage for three different kinds of users:
+///     Self (the declaring class), Friend (classes explicitly named as friends by the access attribute),
+///     and Other (classes that aren't the other two). Using <see cref="AccessPermissions"/> you can define what
+///     operations each of the users is allowed.
+/// </para>
+/// </summary>
+/// <example>
+/// <code>
+///     [RegisterComponent]
+///     // Allow the system with utility functions for this component to modify it.
+///     [Access(typeof(MySystem))]
+///     public sealed class MyComponent : Component
+///     {
+///         public int Counter;
+///     }
+///     <br/>
+///     public sealed class MySystem : EntitySystem
+///     {
+///         public void AddToCounter(Entity&lt;MyComponent&gt; entity)
+///         {
+///             // Works, we're a friend of the other type.
+///             entity.Comp.Counter += 1;
+///         }
+///     }
+///     <br/>
+///     public sealed class OtherSystem : EntitySystem
+///     {
+///         public void AddToCounter(Entity&lt;MyComponent&gt; entity)
+///         {
+///             // Error RS2008: Tried to perform write access to member 'Counter' in type 'MyComponent', despite read access.
+///             entity.Comp.Counter += 1;
+///         }
+///     }
+/// </code>
+/// </example>
+/// <seealso cref="AccessPermissions"/>
 [AttributeUsage(AttributeTargets.Class | AttributeTargets.Interface | AttributeTargets.Struct
                 | AttributeTargets.Field | AttributeTargets.Property | AttributeTargets.Method | AttributeTargets.Constructor)]
 public sealed class AccessAttribute : Attribute
 {
+    /// <summary>
+    ///     The list of types considered "friends" of the type with this attribute.
+    ///     These types get elevated permissions.
+    /// </summary>
+    /// <seealso cref="Friend"/>
     public readonly Type[] Friends;
 
     public const AccessPermissions SelfDefaultPermissions = AccessPermissions.ReadWriteExecute;
@@ -20,7 +67,13 @@ public sealed class AccessAttribute : Attribute
     ///     Access permissions for the type itself, or the type containing the member.
     /// </summary>
     public AccessPermissions Self   { get; set; }  = SelfDefaultPermissions;
+    /// <summary>
+    ///     Access permissions for types specified as <see cref="Friends"/>.
+    /// </summary>
     public AccessPermissions Friend { get; set; }  = FriendDefaultPermissions;
+    /// <summary>
+    ///     Access permissions for types that aren't <see cref="Self"/> and aren't <see cref="Friend"/>.
+    /// </summary>
     public AccessPermissions Other  { get; set;  } = OtherDefaultPermissions;
 
     public AccessAttribute(params Type[] friends)

Robust.Shared/Analyzers/AccessPermissions.cs

@@ -1,18 +1,32 @@
 using System;
+using System.Diagnostics.Contracts;
 
 #if ROBUST_ANALYZERS_IMPL
 namespace Robust.Shared.Analyzers.Implementation;
 #else
 namespace Robust.Shared.Analyzers;
 #endif
 
+/// <summary>
+///     A set of flags that dictate what kind of field and property access can occur for a given <see cref="AccessAttribute"/>.
+/// </summary>
 [Flags]
 public enum AccessPermissions : byte
 {
     None = 0,
 
+    /// <summary>
+    ///     Allows field and property read operations, for example using getters, and also <see cref="PureAttribute"/>
+    ///     marked methods.
+    /// </summary>
     Read    = 1 << 0, // 1
+    /// <summary>
+    ///     Allows field and property write operations, for example using setters.
+    /// </summary>
     Write   = 1 << 1, // 2
+    /// <summary>
+    ///     Allows executing methods.
+    /// </summary>
     Execute = 1 << 2, // 4
 
     ReadWrite        = Read  | Write,

Robust.Shared/Analyzers/ComponentNetworkGeneratorAuxiliary.cs

@@ -9,6 +9,34 @@ namespace Robust.Shared.Analyzers;
 ///     will automatically be replicated using component states to clients. Systems which need to have more intelligent
 ///     component state replication beyond just directly setting variables should not use this attribute.
 /// </summary>
+/// <example>
+/// <code>
+///     // In shared code...
+///     [RegisterComponent, AutoGenerateComponentState]
+///     public sealed class MyComponent : Component
+///     {
+///         // Indicate to the generator we want to network this field.
+///         // Doesn't need to be a DataField for this to work!
+///         [AutoNetworkedField]
+///         public int Counter;
+///     }
+///     <br/>
+///     public sealed class MySystem : EntitySystem
+///     {
+///         public void AddToCounter(Entity&lt;MyComponent&gt; entity)
+///         {
+///             entity.Comp.Counter += 1;
+///             <br/>
+///             // Dirty the entity, and the auto-generated state handling will do the rest to ensure
+///             // all our AutoNetworkedFields are sent to the client.
+///             Dirty(entity);
+///         }
+///     }
+/// </code>
+/// </example>
+/// <seealso cref="AutoNetworkedFieldAttribute"/>
+/// <seealso cref="AfterAutoHandleStateEvent"/>
+/// <seealso cref="ComponentState"/>
 [AttributeUsage(AttributeTargets.Class, Inherited = false)]
 [BaseTypeRequired(typeof(IComponent))]
 public sealed class AutoGenerateComponentStateAttribute : Attribute

Robust.Shared/Analyzers/ComponentPauseGeneratorAttributes.cs

@@ -5,25 +5,30 @@
 namespace Robust.Shared.Analyzers;
 
 /// <summary>
-/// Indicate that a <see cref="Component"/> should automatically handle unpausing of timer fields.
+///     Indicate that a <see cref="Component"/> should automatically handle unpausing of timer fields.
 /// </summary>
 /// <remarks>
-/// When this attribute is set on a <see cref="Component"/>, an <see cref="EntitySystem"/> will automatically be
-/// generated that increments any fields tagged with <see cref="AutoPausedFieldAttribute"/> when the entity is unpaused
-/// (<see cref="EntityUnpausedEvent"/>).
+///     When this attribute is set on a <see cref="Component"/>, an <see cref="EntitySystem"/> will automatically be
+///     generated that increments any fields tagged with <see cref="AutoPausedFieldAttribute"/> when the entity is unpaused
+///     (<see cref="EntityUnpausedEvent"/>).
 /// </remarks>
 [AttributeUsage(AttributeTargets.Class, Inherited = false)]
 [BaseTypeRequired(typeof(IComponent))]
 public sealed class AutoGenerateComponentPauseAttribute : Attribute
 {
+    /// <summary>
+    ///     Whether the generated code should automatically call
+    ///     <see cref="IEntityManager.Dirty(EntityUid,IComponent,MetaDataComponent)"/> after unpausing the entity.
+    ///     This is automatically inferred for fields marked <see cref="AutoNetworkedFieldAttribute"/>.
+    /// </summary>
     public bool Dirty = false;
 }
 
 /// <summary>
-/// Mark a field or property to automatically handle unpausing with <see cref="AutoGenerateComponentPauseAttribute"/>.
+///     Mark a field or property to automatically handle unpausing with <see cref="AutoGenerateComponentPauseAttribute"/>.
 /// </summary>
 /// <remarks>
-/// The type of the field or prototype must be <see cref="TimeSpan"/> (potentially nullable).
+///     The type of the field or prototype must be <see cref="TimeSpan"/> (potentially nullable).
 /// </remarks>
 [AttributeUsage(AttributeTargets.Field | AttributeTargets.Property)]
 public sealed class AutoPausedFieldAttribute : Attribute;

Robust.Shared/Analyzers/ForbidLiteralAttribute.cs

@@ -3,9 +3,26 @@
 namespace Robust.Shared.Analyzers;
 
 /// <summary>
-/// Marks that values used for this parameter should not be literal values.
-/// This helps prevent magic numbers/strings/etc, by indicating that values
-/// should either be wrapped (for validation) or defined as constants or readonly statics.
+///     Marks that values used for this parameter should not be literal values.
+///     This helps prevent magic numbers/strings/etc, by indicating that values
+///     should either be wrapped (for validation) or defined as constants or readonly statics.
 /// </summary>
+/// <example>
+/// <code>
+///     public sealed class MyClass
+///     {
+///         public static bool IsPastry([ForbidLiteral] string id);
+///         public static string GrabFromCupboard();
+///     }
+///     <br/>
+///     <br/>
+///     // Error RA0033: The id parameter of IsPastry forbids literal values.
+///     DebugTools.Assert(MyClass.IsPastry("cupcake"));
+///     <br/>
+///     var maybePastry = obj.GrabFromCupboard();
+///     // Allowed.
+///     DebugTools.Assert(MyClass.IsPastry(maybePastry));
+/// </code>
+/// </example>
 [AttributeUsage(AttributeTargets.Parameter)]
 public sealed class ForbidLiteralAttribute : Attribute;

Robust.Shared/Analyzers/MustCallBaseAttribute.cs

@@ -3,13 +3,40 @@
 namespace Robust.Shared.Analyzers;
 
 /// <summary>
-/// Indicates that overriders of this method must always call the base function.
+///     Indicates that overriders of this method must always call the base function.
 /// </summary>
 /// <param name="onlyOverrides">
-/// If true, only base calls to *overrides* are necessary.
-/// This is intended for base classes where the base function is always empty,
-/// so a base call from the first override may be ommitted.
+///     If true, only base calls to <b>overrides</b> are necessary.
+///     This is intended for base classes where the base function is always empty,
+///     so a base call from the first override may be ommitted.
 /// </param>
+/// <example>
+/// <code>
+///     public abstract class MyBaseClass
+///     {
+///         [MustCallBase]
+///         public virtual void Initialize() { /* ... */ }
+///     }
+///     <br/>
+///     public sealed class MyBadClass : MyBaseClass
+///     {
+///         // Error RA0028: Overriders of this function must always call the base function.
+///         public override void Initialize()
+///         {
+///             // We don't do anything in here, not even call base.Initialize().
+///         }
+///     }
+///     <br/>
+///     public sealed class MyGoodClass : MyBaseClass
+///     {
+///         // No error.
+///         public override void Initialize()
+///         {
+///             base.Initialize();
+///         }
+///     }
+/// </code>
+/// </example>
 [AttributeUsage(AttributeTargets.Method)]
 public sealed class MustCallBaseAttribute(bool onlyOverrides = false) : Attribute
 {

Robust.Shared/Analyzers/NotContentImplementable.cs

@@ -3,11 +3,17 @@
 namespace Robust.Shared.Analyzers;
 
 /// <summary>
-/// Marker attribute specifying that content <b>must not</b> implement this interface itself.
+///     Marker attribute specifying that content <b>must not</b> implement this interface itself.
 /// </summary>
 /// <remarks>
-/// Interfaces with this attribute may have members added by the engine at any time,
-/// so implementing them yourself would not be API-stable.
+/// <para>
+///     Interfaces with this attribute may have members added by the engine at any time,
+///     so implementing them yourself would not be API-stable.
+/// </para>
+/// <para>
+///     Currently, nothing enforces this, but your codebase may spontaneously cease building in any minor version if
+///     you inherit from or implement anything marked with this attribute.
+/// </para>
 /// </remarks>
 [AttributeUsage(AttributeTargets.Interface)]
 public sealed class NotContentImplementableAttribute : Attribute;

Robust.Shared/Analyzers/NotNullableFlagAttribute.cs

@@ -6,6 +6,10 @@ namespace Robust.Shared.Analyzers.Implementation;
 namespace Robust.Shared.Analyzers;
 #endif
 
+/// <summary>
+///     Indicates the given boolean field must be set to true when the provided type parameter is not nullable.
+///     An analyzer then enforces this as an error.
+/// </summary>
 [AttributeUsage(AttributeTargets.Parameter | AttributeTargets.GenericParameter)]
 public sealed class NotNullableFlagAttribute : Attribute
 {

Robust.Shared/Analyzers/ObsoleteInheritanceAttribute.cs

@@ -3,11 +3,20 @@
 namespace Robust.Shared.Analyzers;
 
 /// <summary>
-/// Indicates that the ability to <i>inherit</i> this type is obsolete, and attempting to do so should give a warning.
+///     Indicates that the ability to <i>inherit</i> this type is obsolete, and attempting to do so should give a warning.
 /// </summary>
 /// <remarks>
-/// This is useful to gracefully deal with types that should never have had <see cref="VirtualAttribute"/>.
+///     This is useful to gracefully deal with types that should never have had <see cref="VirtualAttribute"/>.
 /// </remarks>
+/// <example>
+/// <code>
+///     [ObsoleteInheritance]
+///     public class MyClass;
+///     <br/>
+///     // Warning RA0034: Type 'MyDescendant' inherits from 'MyClass', which has obsoleted inheriting from itself.
+///     public sealed class MyDescendant : MyClass;
+/// </code>
+/// </example>
 /// <seealso cref="VirtualAttribute"/>
 [AttributeUsage(AttributeTargets.Class, Inherited = false)]
 public sealed class ObsoleteInheritanceAttribute : Attribute

Robust.Shared/Analyzers/PreferGenericVariantAttribute.cs

@@ -6,6 +6,23 @@ namespace Robust.Shared.Analyzers.Implementation;
 namespace Robust.Shared.Analyzers;
 #endif
 
+/// <summary>
+///     Indicates that the marked method has an alternative version that takes the Type input as a generic,
+///     and warns the user to use the generic version instead if they use <see langword="typeof"/>.
+/// </summary>
+/// <example>
+/// <code>
+///     public sealed MyClass
+///     {
+///         [PreferGenericVariant]
+///         public static bool IsPastry(Type t);
+///         public static bool IsPastry&lt;T&gt;();
+///     }
+///     <br/>
+///     // Warning RA0005: Consider using the generic variant of this method to avoid potential allocations.
+///     MyClass.IsPastry(typeof(Cupcake));
+/// </code>
+/// </example>
 [AttributeUsage(AttributeTargets.Method)]
 public sealed class PreferGenericVariantAttribute : Attribute
 {