From bcfa0c9ae9c507b90aa3c793213890bb203f5b31 Mon Sep 17 00:00:00 2001 From: RoosterDragon Date: Sat, 18 Mar 2023 09:29:56 +0000 Subject: [PATCH] Review StyleCop rules. - Enforce SA1604 ElementDocumentationShouldHaveSummary. - Enforce SA1629 DocumentationTextShouldEndWithAPeriod. - Turn off some rules covered by IDExxxx rules. - Remaining rules are treated as part of OpenRA style. --- .editorconfig | 38 ++++++++++--------- OpenRA.Game/Actor.cs | 2 +- OpenRA.Game/ExternalMods.cs | 10 +++-- OpenRA.Game/FileSystem/FileSystem.cs | 2 +- OpenRA.Game/GameRules/WeaponInfo.cs | 2 +- OpenRA.Game/Graphics/Model.cs | 2 +- OpenRA.Game/Graphics/RgbaColorRenderer.cs | 2 +- OpenRA.Game/Graphics/SpriteLoader.cs | 2 +- OpenRA.Game/Graphics/Util.cs | 14 +++---- OpenRA.Game/Graphics/Viewport.cs | 2 +- OpenRA.Game/Input/HotkeyReference.cs | 2 +- OpenRA.Game/MPos.cs | 2 +- OpenRA.Game/Manifest.cs | 2 +- OpenRA.Game/Map/CellLayer.cs | 4 +- OpenRA.Game/Map/CellLayerBase.cs | 4 +- OpenRA.Game/Map/Map.cs | 4 +- OpenRA.Game/Map/MapCache.cs | 4 +- OpenRA.Game/Map/MapPreview.cs | 2 +- OpenRA.Game/Map/PlayerReference.cs | 2 +- OpenRA.Game/Network/GameServer.cs | 26 ++++++------- OpenRA.Game/Network/OrderManager.cs | 8 +++- OpenRA.Game/Player.cs | 2 +- OpenRA.Game/WAngle.cs | 2 +- OpenRA.Game/WPos.cs | 4 +- OpenRA.Game/WRot.cs | 2 +- OpenRA.Game/Widgets/Widget.cs | 10 ++--- OpenRA.Game/World.cs | 3 +- OpenRA.Mods.Cnc/FileFormats/CRC32.cs | 2 +- OpenRA.Mods.Cnc/FileSystem/MegFile.cs | 2 +- OpenRA.Mods.Common/Activities/Enter.cs | 4 +- .../Activities/FindAndDeliverResources.cs | 2 +- OpenRA.Mods.Common/Pathfinder/CellInfo.cs | 2 +- OpenRA.Mods.Common/Pathfinder/PathSearch.cs | 4 +- OpenRA.Mods.Common/TargetExtensions.cs | 2 +- .../BotModuleLogic/SupportPowerDecision.cs | 6 +-- OpenRA.Mods.Common/Traits/Carryall.cs | 2 +- OpenRA.Mods.Common/UpdateRules/UpdateRule.cs | 4 +- OpenRA.Mods.Common/UpdateRules/UpdateUtils.cs | 14 +++---- OpenRA.Mods.Common/Util.cs | 8 ++-- .../UtilityCommands/Utilities.cs | 1 - .../Widgets/Logic/Ingame/CommandBarLogic.cs | 2 +- OpenRA.Mods.Common/WorldExtensions.cs | 16 ++++---- 42 files changed, 120 insertions(+), 110 deletions(-) diff --git a/.editorconfig b/.editorconfig index f3f3ed272d..5c773a289e 100644 --- a/.editorconfig +++ b/.editorconfig @@ -520,7 +520,7 @@ dotnet_naming_rule.most_symbols_should_be_pascal_case.severity = warning ### StyleCop.Analyzers -### https://github.com/DotNetAnalyzers/StyleCopAnalyzers/tree/master/documentation +### https://github.com/DotNetAnalyzers/StyleCopAnalyzers/blob/master/DOCUMENTATION.md # Below we enable rule categories by setting severity to warning. # We'll only list rules to disable. @@ -536,6 +536,15 @@ dotnet_analyzer_diagnostic.category-StyleCop.CSharp.ReadabilityRules.severity = dotnet_analyzer_diagnostic.category-StyleCop.CSharp.SpacingRules.severity = warning dotnet_analyzer_diagnostic.category-StyleCop.CSharp.SpecialRules.severity = warning +# Rules that are covered by IDE0001 Simplify name +dotnet_diagnostic.SA1125.severity = none # UseShorthandForNullableTypes + +# Rules that are covered by IDE0047 Remove unnecessary parentheses +dotnet_diagnostic.SA1119.severity = none # StatementMustNotUseUnnecessaryParenthesis + +# Rules that are covered by IDE0055 Formatting Rules +dotnet_diagnostic.SA1027.severity = none # UseTabsCorrectly + # Rules that are covered by IDE1006 Naming Rules dotnet_diagnostic.SA1300.severity = none # ElementMustBeginWithUpperCaseLetter dotnet_diagnostic.SA1302.severity = none # InterfaceNamesMustBeginWithI @@ -549,50 +558,45 @@ dotnet_diagnostic.SA1313.severity = none # ParameterNamesMustBeginWithLowerCaseL # Rules that conflict with OpenRA project style conventions dotnet_diagnostic.SA1101.severity = none # PrefixLocalCallsWithThis +dotnet_diagnostic.SA1107.severity = none # CodeMustNotContainMultipleStatementsOnOneLine +dotnet_diagnostic.SA1116.severity = none # SplitParametersMustStartOnLineAfterDeclaration dotnet_diagnostic.SA1117.severity = none # ParametersMustBeOnSameLineOrSeparateLines dotnet_diagnostic.SA1118.severity = none # ParameterMustNotSpanMultipleLines dotnet_diagnostic.SA1122.severity = none # UseStringEmptyForEmptyStrings dotnet_diagnostic.SA1124.severity = none # DoNotUseRegions dotnet_diagnostic.SA1127.severity = none # GenericTypeConstraintsMustBeOnOwnLine +dotnet_diagnostic.SA1132.severity = none # DoNotCombineFields dotnet_diagnostic.SA1135.severity = none # UsingDirectivesMustBeQualified dotnet_diagnostic.SA1136.severity = none # EnumValuesShouldBeOnSeparateLines dotnet_diagnostic.SA1200.severity = none # UsingDirectivesMustBePlacedCorrectly dotnet_diagnostic.SA1201.severity = none # ElementsMustAppearInTheCorrectOrder dotnet_diagnostic.SA1202.severity = none # ElementsMustBeOrderedByAccess +dotnet_diagnostic.SA1204.severity = none # StaticElementsMustAppearBeforeInstanceElements +dotnet_diagnostic.SA1214.severity = none # ReadonlyElementsMustAppearBeforeNonReadonlyElements +dotnet_diagnostic.SX1309.severity = none # FieldNamesMustBeginWithUnderscore +dotnet_diagnostic.SX1309S.severity = none # StaticFieldNamesMustBeginWithUnderscore dotnet_diagnostic.SA1314.severity = none # TypeParameterNamesMustBeginWithT dotnet_diagnostic.SA1400.severity = none # AccessModifierMustBeDeclared dotnet_diagnostic.SA1401.severity = none # FieldsMustBePrivate dotnet_diagnostic.SA1402.severity = none # FileMayOnlyContainASingleType dotnet_diagnostic.SA1407.severity = none # ArithmeticExpressionsMustDeclarePrecedence +dotnet_diagnostic.SA1413.severity = none # UseTrailingCommasInMultiLineInitializers dotnet_diagnostic.SA1501.severity = none # StatementMustNotBeOnSingleLine dotnet_diagnostic.SA1502.severity = none # ElementMustNotBeOnSingleLine dotnet_diagnostic.SA1503.severity = none # BracesMustNotBeOmitted +dotnet_diagnostic.SA1516.severity = none # ElementsMustBeSeparatedByBlankLine dotnet_diagnostic.SA1519.severity = none # BracesMustNotBeOmittedFromMultiLineChildStatement dotnet_diagnostic.SA1520.severity = none # UseBracesConsistently dotnet_diagnostic.SA1600.severity = none # ElementsMustBeDocumented dotnet_diagnostic.SA1601.severity = none # PartialElementsMustBeDocumented dotnet_diagnostic.SA1602.severity = none # EnumerationItemsMustBeDocumented -dotnet_diagnostic.SA1633.severity = none # FileMustHaveHeader -dotnet_diagnostic.SA1649.severity = none # FileNameMustMatchTypeName - -# Rules that could potentially be enabled after existing violations are fixed -dotnet_diagnostic.SA1027.severity = none # UseTabsCorrectly -dotnet_diagnostic.SA1107.severity = none # CodeMustNotContainMultipleStatementsOnOneLine -dotnet_diagnostic.SA1116.severity = none # SplitParametersMustStartOnLineAfterDeclaration -dotnet_diagnostic.SA1119.severity = none # StatementMustNotUseUnnecessaryParenthesis -dotnet_diagnostic.SA1132.severity = none # DoNotCombineFields -dotnet_diagnostic.SA1204.severity = none # StaticElementsMustAppearBeforeInstanceElements -dotnet_diagnostic.SA1214.severity = none # ReadonlyElementsMustAppearBeforeNonReadonlyElements -dotnet_diagnostic.SA1413.severity = none # UseTrailingCommasInMultiLineInitializers -dotnet_diagnostic.SA1516.severity = none # ElementsMustBeSeparatedByBlankLine -dotnet_diagnostic.SA1604.severity = none # ElementDocumentationShouldHaveSummary dotnet_diagnostic.SA1611.severity = none # ElementParametersShouldBeDocumented dotnet_diagnostic.SA1615.severity = none # ElementReturnValueShouldBeDocumented dotnet_diagnostic.SA1618.severity = none # GenericTypeParametersShouldBeDocumented dotnet_diagnostic.SA1623.severity = none # PropertySummaryDocumentationShouldMatchAccessors -dotnet_diagnostic.SA1629.severity = none # DocumentationTextShouldEndWithAPeriod +dotnet_diagnostic.SA1633.severity = none # FileMustHaveHeader dotnet_diagnostic.SA1642.severity = none # ConstructorSummaryDocumentationShouldBeginWithStandardText - +dotnet_diagnostic.SA1649.severity = none # FileNameMustMatchTypeName #### Code Quality Rules #### https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/quality-rules/ diff --git a/OpenRA.Game/Actor.cs b/OpenRA.Game/Actor.cs index 70bb100225..12164c9b98 100644 --- a/OpenRA.Game/Actor.cs +++ b/OpenRA.Game/Actor.cs @@ -587,7 +587,7 @@ namespace OpenRA return InvalidConditionToken; } - /// Returns whether the specified token is valid for RevokeCondition + /// Returns whether the specified token is valid for RevokeCondition. public bool TokenValid(int token) { return conditionTokens.ContainsKey(token); diff --git a/OpenRA.Game/ExternalMods.cs b/OpenRA.Game/ExternalMods.cs index ddc9a9e12d..6c8ecf1c15 100644 --- a/OpenRA.Game/ExternalMods.cs +++ b/OpenRA.Game/ExternalMods.cs @@ -181,10 +181,12 @@ namespace OpenRA /// /// Removes invalid mod registrations: - /// * LaunchPath no longer exists - /// * LaunchPath and mod id matches the active mod, but the version is different - /// * Filename doesn't match internal key - /// * Fails to parse as a mod registration + /// + /// LaunchPath no longer exists. + /// LaunchPath and mod id matches the active mod, but the version is different. + /// Filename doesn't match internal key. + /// Fails to parse as a mod registration. + /// /// internal void ClearInvalidRegistrations(ModRegistration registration) { diff --git a/OpenRA.Game/FileSystem/FileSystem.cs b/OpenRA.Game/FileSystem/FileSystem.cs index eaab785189..e2c598e9ce 100644 --- a/OpenRA.Game/FileSystem/FileSystem.cs +++ b/OpenRA.Game/FileSystem/FileSystem.cs @@ -271,7 +271,7 @@ namespace OpenRA.FileSystem } /// - /// Returns true if the given filename references an external mod via an explicit mount + /// Returns true if the given filename references an external mod via an explicit mount. /// public bool IsExternalModFile(string filename) { diff --git a/OpenRA.Game/GameRules/WeaponInfo.cs b/OpenRA.Game/GameRules/WeaponInfo.cs index e2d221e3ad..cbbc97d071 100644 --- a/OpenRA.Game/GameRules/WeaponInfo.cs +++ b/OpenRA.Game/GameRules/WeaponInfo.cs @@ -131,7 +131,7 @@ namespace OpenRA.GameRules public readonly List Warheads = new List(); /// - /// This constructor is used solely for documentation generation! + /// This constructor is used solely for documentation generation. /// public WeaponInfo() { } diff --git a/OpenRA.Game/Graphics/Model.cs b/OpenRA.Game/Graphics/Model.cs index cd246961cb..458f24af96 100644 --- a/OpenRA.Game/Graphics/Model.cs +++ b/OpenRA.Game/Graphics/Model.cs @@ -26,7 +26,7 @@ namespace OpenRA.Graphics float[] Bounds(uint frame); ModelRenderData RenderData(uint section); - /// Returns the smallest rectangle that covers all rotations of all frames in a model + /// Returns the smallest rectangle that covers all rotations of all frames in a model. Rectangle AggregateBounds { get; } } diff --git a/OpenRA.Game/Graphics/RgbaColorRenderer.cs b/OpenRA.Game/Graphics/RgbaColorRenderer.cs index e016c14553..5e74088d45 100644 --- a/OpenRA.Game/Graphics/RgbaColorRenderer.cs +++ b/OpenRA.Game/Graphics/RgbaColorRenderer.cs @@ -78,7 +78,7 @@ namespace OpenRA.Graphics /// /// Calculate the 2D intersection of two lines. /// Will behave badly if the lines are parallel. - /// Z position is the average of a and b (ignores actual intersection point if it exists) + /// Z position is the average of a and b (ignores actual intersection point if it exists). /// float3 IntersectionOf(in float3 a, in float3 da, in float3 b, in float3 db) { diff --git a/OpenRA.Game/Graphics/SpriteLoader.cs b/OpenRA.Game/Graphics/SpriteLoader.cs index ebb96a1e46..420ae9141d 100644 --- a/OpenRA.Game/Graphics/SpriteLoader.cs +++ b/OpenRA.Game/Graphics/SpriteLoader.cs @@ -18,7 +18,7 @@ namespace OpenRA.Graphics /// /// Describes the format of the pixel data in a ISpriteFrame. /// Note that the channel order is defined for little-endian bytes, so BGRA corresponds - /// to a 32bit ARGB value, such as that returned by Color.ToArgb()! + /// to a 32bit ARGB value, such as that returned by Color.ToArgb(). /// public enum SpriteFrameType { diff --git a/OpenRA.Game/Graphics/Util.cs b/OpenRA.Game/Graphics/Util.cs index c4dbd0941d..925f48b24c 100644 --- a/OpenRA.Game/Graphics/Util.cs +++ b/OpenRA.Game/Graphics/Util.cs @@ -224,10 +224,10 @@ namespace OpenRA.Graphics } /// Rotates a quad about its center in the x-y plane. - /// The top left vertex of the quad - /// A float3 containing the X, Y, and Z lengths of the quad - /// The number of radians to rotate by - /// An array of four vertices representing the rotated quad (top-left, top-right, bottom-right, bottom-left) + /// The top left vertex of the quad. + /// A float3 containing the X, Y, and Z lengths of the quad. + /// The number of radians to rotate by. + /// An array of four vertices representing the rotated quad (top-left, top-right, bottom-right, bottom-left). public static float3[] RotateQuad(float3 tl, float3 size, float rotation) { var center = tl + 0.5f * size; @@ -258,9 +258,9 @@ namespace OpenRA.Graphics /// /// Returns the bounds of an object. Used for determining which objects need to be rendered on screen, and which do not. /// - /// The top left vertex of the object - /// A float 3 containing the X, Y, and Z lengths of the object - /// The angle to rotate the object by (use 0f if there is no rotation) + /// The top left vertex of the object. + /// A float 3 containing the X, Y, and Z lengths of the object. + /// The angle to rotate the object by (use 0f if there is no rotation). public static Rectangle BoundingRectangle(float3 offset, float3 size, float rotation) { if (rotation == 0f) diff --git a/OpenRA.Game/Graphics/Viewport.cs b/OpenRA.Game/Graphics/Viewport.cs index f55520f69a..d51cc90671 100644 --- a/OpenRA.Game/Graphics/Viewport.cs +++ b/OpenRA.Game/Graphics/Viewport.cs @@ -278,7 +278,7 @@ namespace OpenRA.Graphics return worldRenderer.World.Map.CellContaining(worldRenderer.ProjectedPosition(ViewToWorldPx(view))); } - /// Returns an unfiltered list of all cells that could potentially contain the mouse cursor + /// Returns an unfiltered list of all cells that could potentially contain the mouse cursor. IEnumerable CandidateMouseoverCells(int2 world) { var map = worldRenderer.World.Map; diff --git a/OpenRA.Game/Input/HotkeyReference.cs b/OpenRA.Game/Input/HotkeyReference.cs index d352cf6af1..3582af0301 100644 --- a/OpenRA.Game/Input/HotkeyReference.cs +++ b/OpenRA.Game/Input/HotkeyReference.cs @@ -14,7 +14,7 @@ using System; namespace OpenRA { /// - /// A reference to either a named hotkey (defined in the game settings) or a statically assigned hotkey + /// A reference to either a named hotkey (defined in the game settings) or a statically assigned hotkey. /// public class HotkeyReference { diff --git a/OpenRA.Game/MPos.cs b/OpenRA.Game/MPos.cs index 9793f0926e..51f2701942 100644 --- a/OpenRA.Game/MPos.cs +++ b/OpenRA.Game/MPos.cs @@ -64,7 +64,7 @@ namespace OpenRA } /// - /// Projected map position + /// Projected map position. /// public readonly struct PPos : IEquatable { diff --git a/OpenRA.Game/Manifest.cs b/OpenRA.Game/Manifest.cs index 87b20116b3..ae29309b29 100644 --- a/OpenRA.Game/Manifest.cs +++ b/OpenRA.Game/Manifest.cs @@ -64,7 +64,7 @@ namespace OpenRA public bool Hidden; } - /// Describes what is to be loaded in order to run a mod. + /// Describes what is to be loaded in order to run a mod. public class Manifest : IDisposable { public readonly string Id; diff --git a/OpenRA.Game/Map/CellLayer.cs b/OpenRA.Game/Map/CellLayer.cs index 9644bbdd39..409d377d6c 100644 --- a/OpenRA.Game/Map/CellLayer.cs +++ b/OpenRA.Game/Map/CellLayer.cs @@ -72,7 +72,7 @@ namespace OpenRA return uv.V * Size.Width + uv.U; } - /// Gets or sets the using cell coordinates + /// Gets or sets the using cell coordinates. public T this[CPos cell] { get => Entries[Index(cell)]; @@ -85,7 +85,7 @@ namespace OpenRA } } - /// Gets or sets the layer contents using raw map coordinates (not CPos!) + /// Gets or sets the layer contents using raw map coordinates (not CPos!). public T this[MPos uv] { get => Entries[Index(uv)]; diff --git a/OpenRA.Game/Map/CellLayerBase.cs b/OpenRA.Game/Map/CellLayerBase.cs index d66b638f01..1c2e7a9972 100644 --- a/OpenRA.Game/Map/CellLayerBase.cs +++ b/OpenRA.Game/Map/CellLayerBase.cs @@ -43,13 +43,13 @@ namespace OpenRA Array.Copy(anotherLayer.Entries, Entries, Entries.Length); } - /// Clears the layer contents with their default value + /// Clears the layer contents with their default value. public virtual void Clear() { Array.Clear(Entries, 0, Entries.Length); } - /// Clears the layer contents with a known value + /// Clears the layer contents with a known value. public virtual void Clear(T clearValue) { Array.Fill(Entries, clearValue); diff --git a/OpenRA.Game/Map/Map.cs b/OpenRA.Game/Map/Map.cs index f5c70dc60a..7daedfec73 100644 --- a/OpenRA.Game/Map/Map.cs +++ b/OpenRA.Game/Map/Map.cs @@ -155,7 +155,7 @@ namespace OpenRA public const int CurrentMapFormat = 12; const short InvalidCachedTerrainIndex = -1; - /// Defines the order of the fields in map.yaml + /// Defines the order of the fields in map.yaml. static readonly MapField[] YamlFields = { new MapField("MapFormat"), @@ -993,7 +993,7 @@ namespace OpenRA } /// - /// The size of the map Height step in world units + /// The size of the map Height step in world units. /// /// RectangularIsometric defines 1024 units along the diagonal axis, /// giving a half-tile height step of sqrt(2) * 512 diff --git a/OpenRA.Game/Map/MapCache.cs b/OpenRA.Game/Map/MapCache.cs index e665cfac73..ccbdefd670 100644 --- a/OpenRA.Game/Map/MapCache.cs +++ b/OpenRA.Game/Map/MapCache.cs @@ -43,7 +43,7 @@ namespace OpenRA readonly List mapDirectoryTrackers = new List(); /// - /// The most recently modified or loaded map at runtime + /// The most recently modified or loaded map at runtime. /// public string LastModifiedMap { get; private set; } = null; readonly Dictionary mapUpdates = new Dictionary(); @@ -51,7 +51,7 @@ namespace OpenRA string lastLoadedLastModifiedMap; /// - /// If LastModifiedMap was picked already, returns a null + /// If LastModifiedMap was picked already, returns a null. /// public string PickLastModifiedMap(MapVisibility visibility) { diff --git a/OpenRA.Game/Map/MapPreview.cs b/OpenRA.Game/Map/MapPreview.cs index eba86340cd..5a49959e4f 100644 --- a/OpenRA.Game/Map/MapPreview.cs +++ b/OpenRA.Game/Map/MapPreview.cs @@ -63,7 +63,7 @@ namespace OpenRA public class MapPreview : IDisposable, IReadOnlyFileSystem { - /// Wrapper that enables map data to be replaced in an atomic fashion + /// Wrapper that enables map data to be replaced in an atomic fashion. class InnerData { public int MapFormat; diff --git a/OpenRA.Game/Map/PlayerReference.cs b/OpenRA.Game/Map/PlayerReference.cs index 531ea8aa3a..5c3a4beae7 100644 --- a/OpenRA.Game/Map/PlayerReference.cs +++ b/OpenRA.Game/Map/PlayerReference.cs @@ -36,7 +36,7 @@ namespace OpenRA /// /// Sets the "Home" location, which can be used by traits and scripts to e.g. set the initial camera /// location or choose the map edge for reinforcements. - /// This will usually be overridden for client (lobby slot) players with a location based on the Spawn index + /// This will usually be overridden for client (lobby slot) players with a location based on the Spawn index. /// public CPos HomeLocation = CPos.Zero; diff --git a/OpenRA.Game/Network/GameServer.cs b/OpenRA.Game/Network/GameServer.cs index 53c508721a..104b0d8f3f 100644 --- a/OpenRA.Game/Network/GameServer.cs +++ b/OpenRA.Game/Network/GameServer.cs @@ -61,34 +61,34 @@ namespace OpenRA.Network public const int ProtocolVersion = 2; - /// Online game number or -1 for LAN games + /// Online game number or -1 for LAN games. public readonly int Id = -1; - /// Name of the server + /// Name of the server. public readonly string Name = null; /// ip:port string to connect to. public readonly string Address = null; - /// Port of the server + /// Port of the server. public readonly int Port = 0; - /// The current state of the server (waiting/playing/completed) + /// The current state of the server (waiting/playing/completed). public readonly int State = 0; - /// The number of slots available for non-bot players + /// The number of slots available for non-bot players. public readonly int MaxPlayers = 0; - /// UID of the map + /// UID of the map. public readonly string Map = null; - /// Mod ID + /// Mod ID. public readonly string Mod = ""; - /// Mod Version + /// Mod Version. public readonly string Version = ""; - /// Human-readable mod title + /// Human-readable mod title. public readonly string ModTitle = ""; /// URL to show in game listings for custom/unknown mods. @@ -100,13 +100,13 @@ namespace OpenRA.Network /// GeoIP resolved server location. public readonly string Location = ""; - /// Password protected + /// Password protected. public readonly bool Protected = false; - /// Players must be authenticated with the OpenRA forum + /// Players must be authenticated with the OpenRA forum. public readonly bool Authentication = false; - /// UTC datetime string when the game changed to the Playing state + /// UTC datetime string when the game changed to the Playing state. public readonly string Started = null; /// Number of non-spectator, non-bot players. Only defined if GameServer is parsed from yaml. @@ -132,7 +132,7 @@ namespace OpenRA.Network [FieldLoader.LoadUsing(nameof(LoadClients))] public readonly GameClient[] Clients; - /// The list of spawnpoints that are disabled for this game + /// The list of spawnpoints that are disabled for this game. public readonly int[] DisabledSpawnPoints = Array.Empty(); public string ModLabel => $"{ModTitle} ({Version})"; diff --git a/OpenRA.Game/Network/OrderManager.cs b/OpenRA.Game/Network/OrderManager.cs index 640926c3b8..9cb0b2aa97 100644 --- a/OpenRA.Game/Network/OrderManager.cs +++ b/OpenRA.Game/Network/OrderManager.cs @@ -28,7 +28,7 @@ namespace OpenRA.Network public Session LobbyInfo = new Session(); - /// Null when watching a replay + /// Null when watching a replay. public Session.Client LocalClient => LobbyInfo.ClientWithIndex(Connection.LocalClientId); public World World; public int OrderQueueLength => pendingOrders.Count > 0 ? pendingOrders.Min(q => q.Value.Count) : 0; @@ -58,7 +58,11 @@ namespace OpenRA.Network int sentOrdersFrame = 0; float tickScale = 1f; - /// Should only be set in + /// + /// Indicates if the world state of other players or a replay has diverged from the local state. + /// The game cannot reliably continue in this condition and is unusable. + /// + /// Should only be set in . public bool IsOutOfSync { get; private set; } = false; public struct ClientOrder diff --git a/OpenRA.Game/Player.cs b/OpenRA.Game/Player.cs index fc6556cbd1..02471e9822 100644 --- a/OpenRA.Game/Player.cs +++ b/OpenRA.Game/Player.cs @@ -253,7 +253,7 @@ namespace OpenRA return PlayerRelationship.Neutral; } - /// returns true if player is null + /// Returns true if player is null. public bool IsAlliedWith(Player p) { return RelationshipWith(p) == PlayerRelationship.Ally; diff --git a/OpenRA.Game/WAngle.cs b/OpenRA.Game/WAngle.cs index c4f6378e52..f9c9105c11 100644 --- a/OpenRA.Game/WAngle.cs +++ b/OpenRA.Game/WAngle.cs @@ -102,7 +102,7 @@ namespace OpenRA /// /// Find the index of CosineTable that has the value closest to the given value. - /// The first or last index will be returned for values above or below the valid range + /// The first or last index will be returned for values above or below the valid range. /// static int ClosestCosineIndex(int value) { diff --git a/OpenRA.Game/WPos.cs b/OpenRA.Game/WPos.cs index 7ad7774555..1464e608fc 100644 --- a/OpenRA.Game/WPos.cs +++ b/OpenRA.Game/WPos.cs @@ -37,12 +37,12 @@ namespace OpenRA public static bool operator !=(in WPos me, in WPos other) { return !(me == other); } /// - /// Returns the linear interpolation between points 'a' and 'b' + /// Returns the linear interpolation between points 'a' and 'b'. /// public static WPos Lerp(in WPos a, in WPos b, int mul, int div) { return a + (b - a) * mul / div; } /// - /// Returns the linear interpolation between points 'a' and 'b' + /// Returns the linear interpolation between points 'a' and 'b'. /// public static WPos Lerp(in WPos a, in WPos b, long mul, long div) { diff --git a/OpenRA.Game/WRot.cs b/OpenRA.Game/WRot.cs index 656067cf32..113a21fd39 100644 --- a/OpenRA.Game/WRot.cs +++ b/OpenRA.Game/WRot.cs @@ -53,7 +53,7 @@ namespace OpenRA /// /// Construct a rotation from an axis and angle. - /// The axis is expected to be normalized to length 1024 + /// The axis is expected to be normalized to length 1024. /// public WRot(WVec axis, WAngle angle) { diff --git a/OpenRA.Game/Widgets/Widget.cs b/OpenRA.Game/Widgets/Widget.cs index 66611efe51..1c9fafefcd 100644 --- a/OpenRA.Game/Widgets/Widget.cs +++ b/OpenRA.Game/Widgets/Widget.cs @@ -125,9 +125,9 @@ namespace OpenRA.Widgets return handled; } - /// Possibly handle keyboard input (if this widget has keyboard focus) - /// true, if keyboard input was handled, false if the input should bubble to the parent widget - /// Key input data + /// Possibly handle keyboard input (if this widget has keyboard focus). + /// true, if keyboard input was handled, false if the input should bubble to the parent widget. + /// Key input data. public static bool HandleKeyPress(KeyInput e) { if (KeyboardFocusWidget != null) @@ -395,8 +395,8 @@ namespace OpenRA.Widgets public virtual void MouseExited() { } /// Possibly handles mouse input (click, drag, scroll, etc). - /// true, if mouse input was handled, false if the input should bubble to the parent widget - /// Mouse input data + /// true, if mouse input was handled, false if the input should bubble to the parent widget. + /// Mouse input data. public virtual bool HandleMouseInput(MouseInput mi) { return false; } public bool HandleMouseInputOuter(MouseInput mi) diff --git a/OpenRA.Game/World.cs b/OpenRA.Game/World.cs index 8b83e5bf61..aa3d83f716 100644 --- a/OpenRA.Game/World.cs +++ b/OpenRA.Game/World.cs @@ -69,7 +69,8 @@ namespace OpenRA public event Action GameOver = () => { }; - /// Should only be set in + /// Indicates that the game has ended. + /// Should only be set in . public bool IsGameOver { get; private set; } public void EndGame() { diff --git a/OpenRA.Mods.Cnc/FileFormats/CRC32.cs b/OpenRA.Mods.Cnc/FileFormats/CRC32.cs index 2d9c9e607c..afe7aa139e 100644 --- a/OpenRA.Mods.Cnc/FileFormats/CRC32.cs +++ b/OpenRA.Mods.Cnc/FileFormats/CRC32.cs @@ -20,7 +20,7 @@ namespace OpenRA.Mods.Cnc.FileFormats public static class CRC32 { /// - /// The CRC32 lookup table + /// The CRC32 lookup table. /// static readonly uint[] LookUp = new uint[256] { diff --git a/OpenRA.Mods.Cnc/FileSystem/MegFile.cs b/OpenRA.Mods.Cnc/FileSystem/MegFile.cs index 8f06f3eb73..3519023458 100644 --- a/OpenRA.Mods.Cnc/FileSystem/MegFile.cs +++ b/OpenRA.Mods.Cnc/FileSystem/MegFile.cs @@ -19,7 +19,7 @@ namespace OpenRA.Mods.Cnc.FileSystem { /// /// This class supports loading unencrypted V3 .meg files using - /// reference documentation from here https://modtools.petrolution.net/docs/MegFileFormat + /// reference documentation from here https://modtools.petrolution.net/docs/MegFileFormat. /// public class MegV3Loader : IPackageLoader { diff --git a/OpenRA.Mods.Common/Activities/Enter.cs b/OpenRA.Mods.Common/Activities/Enter.cs index 815a446dd4..925a9bed47 100644 --- a/OpenRA.Mods.Common/Activities/Enter.cs +++ b/OpenRA.Mods.Common/Activities/Enter.cs @@ -41,14 +41,14 @@ namespace OpenRA.Mods.Common.Activities /// /// Called early in the activity tick to allow subclasses to update state. - /// Call Cancel(self, true) if it is no longer valid to enter + /// Call Cancel(self, true) if it is no longer valid to enter. /// protected virtual void TickInner(Actor self, in Target target, bool targetIsDeadOrHiddenActor) { } /// /// Called when the actor is ready to transition from approaching to entering the target actor. /// Return true to start entering, or false to wait in the WaitingToEnter state. - /// Call Cancel(self, true) before returning false if it is no longer valid to enter + /// Call Cancel(self, true) before returning false if it is no longer valid to enter. /// protected virtual bool TryStartEnter(Actor self, Actor targetActor) { return true; } diff --git a/OpenRA.Mods.Common/Activities/FindAndDeliverResources.cs b/OpenRA.Mods.Common/Activities/FindAndDeliverResources.cs index 1af04fc48f..1a9b612500 100644 --- a/OpenRA.Mods.Common/Activities/FindAndDeliverResources.cs +++ b/OpenRA.Mods.Common/Activities/FindAndDeliverResources.cs @@ -152,7 +152,7 @@ namespace OpenRA.Mods.Common.Activities /// /// Finds the closest harvestable pos between the current position of the harvester - /// and the last order location + /// and the last order location. /// CPos? ClosestHarvestablePos(Actor self) { diff --git a/OpenRA.Mods.Common/Pathfinder/CellInfo.cs b/OpenRA.Mods.Common/Pathfinder/CellInfo.cs index 08799e12cb..c5c487f277 100644 --- a/OpenRA.Mods.Common/Pathfinder/CellInfo.cs +++ b/OpenRA.Mods.Common/Pathfinder/CellInfo.cs @@ -15,7 +15,7 @@ namespace OpenRA.Mods.Common.Pathfinder { /// /// Describes the three states that a node in the graph can have. - /// Based on A* algorithm specification + /// Based on A* algorithm specification. /// public enum CellStatus : byte { diff --git a/OpenRA.Mods.Common/Pathfinder/PathSearch.cs b/OpenRA.Mods.Common/Pathfinder/PathSearch.cs index befff0d755..eea0d60fc8 100644 --- a/OpenRA.Mods.Common/Pathfinder/PathSearch.cs +++ b/OpenRA.Mods.Common/Pathfinder/PathSearch.cs @@ -219,9 +219,9 @@ namespace OpenRA.Mods.Common.Pathfinder /// /// This function analyzes the neighbors of the most promising node in the pathfinding graph - /// using the A* algorithm (A-star) and returns that node + /// using the A* algorithm (A-star) and returns that node. /// - /// The most promising node of the iteration + /// The most promising node of the iteration. CPos Expand() { var currentMinNode = openQueue.Pop().Destination; diff --git a/OpenRA.Mods.Common/TargetExtensions.cs b/OpenRA.Mods.Common/TargetExtensions.cs index 9ed785a963..9f3642c031 100644 --- a/OpenRA.Mods.Common/TargetExtensions.cs +++ b/OpenRA.Mods.Common/TargetExtensions.cs @@ -18,7 +18,7 @@ namespace OpenRA.Mods.Common /// /// Update (Frozen)Actor targets to account for visibility changes or actor replacement. /// If the target actor becomes hidden without a FrozenActor, the target is invalidated. - /// /// + /// public static Target RecalculateInvalidatingHiddenTargets(this Target t, Player viewer) { var updated = t.Recalculate(viewer, out var targetIsHiddenActor); diff --git a/OpenRA.Mods.Common/Traits/BotModules/BotModuleLogic/SupportPowerDecision.cs b/OpenRA.Mods.Common/Traits/BotModules/BotModuleLogic/SupportPowerDecision.cs index 7a5e5c6f6a..dffd6925ff 100644 --- a/OpenRA.Mods.Common/Traits/BotModules/BotModuleLogic/SupportPowerDecision.cs +++ b/OpenRA.Mods.Common/Traits/BotModules/BotModuleLogic/SupportPowerDecision.cs @@ -55,7 +55,7 @@ namespace OpenRA.Mods.Common.Traits return ret; } - /// Evaluates the attractiveness of a position according to all considerations + /// Evaluates the attractiveness of a position according to all considerations. public int GetAttractiveness(WPos pos, Player firedBy) { var answer = 0; @@ -86,7 +86,7 @@ namespace OpenRA.Mods.Common.Traits return answer; } - /// Evaluates the attractiveness of a group of actors according to all considerations + /// Evaluates the attractiveness of a group of actors according to all considerations. public int GetAttractiveness(IEnumerable actors, Player firedBy) { var answer = 0; @@ -137,7 +137,7 @@ namespace OpenRA.Mods.Common.Traits FieldLoader.Load(this, yaml); } - /// Evaluates a single actor according to the rules defined in this consideration + /// Evaluates a single actor according to the rules defined in this consideration. public int GetAttractiveness(Actor a, PlayerRelationship stance, Player firedBy) { if (stance != Against) diff --git a/OpenRA.Mods.Common/Traits/Carryall.cs b/OpenRA.Mods.Common/Traits/Carryall.cs index 1d0f9cea2e..85ce2677ca 100644 --- a/OpenRA.Mods.Common/Traits/Carryall.cs +++ b/OpenRA.Mods.Common/Traits/Carryall.cs @@ -111,7 +111,7 @@ namespace OpenRA.Mods.Common.Traits int carryConditionToken = Actor.InvalidConditionToken; int carryableConditionToken = Actor.InvalidConditionToken; - /// Offset between the carryall's and the carried actor's CenterPositions + /// Offset between the carryall's and the carried actor's CenterPositions. public WVec CarryableOffset { get; private set; } public Carryall(Actor self, CarryallInfo info) diff --git a/OpenRA.Mods.Common/UpdateRules/UpdateRule.cs b/OpenRA.Mods.Common/UpdateRules/UpdateRule.cs index 4f35c5dd55..5589de3c96 100644 --- a/OpenRA.Mods.Common/UpdateRules/UpdateRule.cs +++ b/OpenRA.Mods.Common/UpdateRules/UpdateRule.cs @@ -19,11 +19,11 @@ namespace OpenRA.Mods.Common.UpdateRules public abstract string Description { get; } /// Defines a transformation that is run on each top-level node in a yaml file set. - /// An enumerable of manual steps to be run by the user + /// An enumerable of manual steps to be run by the user. public delegate IEnumerable TopLevelNodeTransform(ModData modData, MiniYamlNode node); /// Defines a transformation that is run on each widget node in a chrome yaml file set. - /// An enumerable of manual steps to be run by the user + /// An enumerable of manual steps to be run by the user. public delegate IEnumerable ChromeNodeTransform(ModData modData, MiniYamlNode widgetNode); public virtual IEnumerable UpdateActorNode(ModData modData, MiniYamlNode actorNode) { yield break; } diff --git a/OpenRA.Mods.Common/UpdateRules/UpdateUtils.cs b/OpenRA.Mods.Common/UpdateRules/UpdateUtils.cs index 3439e6f736..ae1a7ec6a9 100644 --- a/OpenRA.Mods.Common/UpdateRules/UpdateUtils.cs +++ b/OpenRA.Mods.Common/UpdateRules/UpdateUtils.cs @@ -315,13 +315,13 @@ namespace OpenRA.Mods.Common.UpdateRules } } - /// Checks if node is a removal (has '-' prefix) + /// Checks if node is a removal (has '-' prefix). public static bool IsRemoval(this MiniYamlNode node) { return node.Key[0].ToString() == "-"; } - /// Renames a yaml key preserving any @suffix + /// Renames a yaml key preserving any @suffix. public static void RenameKey(this MiniYamlNode node, string newKey, bool preserveSuffix = true, bool includeRemovals = true) { var prefix = includeRemovals && node.IsRemoval() ? "-" : ""; @@ -370,13 +370,13 @@ namespace OpenRA.Mods.Common.UpdateRules node.MoveNode(fromNode, toNode); } - /// Removes children with keys equal to [match] or [match]@[arbitrary suffix] + /// Removes children with keys equal to [match] or [match]@[arbitrary suffix]. public static int RemoveNodes(this MiniYamlNode node, string match, bool ignoreSuffix = true, bool includeRemovals = true) { return node.Value.Nodes.RemoveAll(n => n.KeyMatches(match, ignoreSuffix, includeRemovals)); } - /// Returns true if the node is of the form [match] or [match]@[arbitrary suffix] + /// Returns true if the node is of the form [match] or [match]@[arbitrary suffix]. public static bool KeyMatches(this MiniYamlNode node, string match, bool ignoreSuffix = true, bool includeRemovals = true) { if (node.Key == null) @@ -394,7 +394,7 @@ namespace OpenRA.Mods.Common.UpdateRules return atPosition > 0 && node.Key.Substring(0, atPosition) == prefix + match; } - /// Returns true if the node is of the form [match], [match]@[arbitrary suffix] or [arbitrary suffix]@[match] + /// Returns true if the node is of the form [match], [match]@[arbitrary suffix] or [arbitrary suffix]@[match]. public static bool KeyContains(this MiniYamlNode node, string match, bool ignoreSuffix = true, bool includeRemovals = true) { if (node.Key == null) @@ -409,13 +409,13 @@ namespace OpenRA.Mods.Common.UpdateRules return false; } - /// Returns children with keys equal to [match] or [match]@[arbitrary suffix] + /// Returns children with keys equal to [match] or [match]@[arbitrary suffix]. public static IEnumerable ChildrenMatching(this MiniYamlNode node, string match, bool ignoreSuffix = true, bool includeRemovals = true) { return node.Value.Nodes.Where(n => n.KeyMatches(match, ignoreSuffix, includeRemovals)); } - /// Returns children whose keys contain 'match' (optionally in the suffix) + /// Returns children whose keys contain 'match' (optionally in the suffix). public static IEnumerable ChildrenContaining(this MiniYamlNode node, string match, bool ignoreSuffix = true, bool includeRemovals = true) { return node.Value.Nodes.Where(n => n.KeyContains(match, ignoreSuffix, includeRemovals)); diff --git a/OpenRA.Mods.Common/Util.cs b/OpenRA.Mods.Common/Util.cs index fca31ffcb3..8774e23e2b 100644 --- a/OpenRA.Mods.Common/Util.cs +++ b/OpenRA.Mods.Common/Util.cs @@ -41,7 +41,7 @@ namespace OpenRA.Mods.Common /// /// Adds step angle units to facing in the direction that takes it closer to desiredFacing. /// If facing is already within step of desiredFacing then desiredFacing is returned. - /// Step is given as an integer to allow negative values (step away from the desired facing) + /// Step is given as an integer to allow negative values (step away from the desired facing). /// public static WAngle TickFacing(WAngle facing, WAngle desiredFacing, WAngle step) { @@ -55,7 +55,7 @@ namespace OpenRA.Mods.Common /// /// Determines whether desiredFacing is clockwise (-1) or anticlockwise (+1) of facing. - /// If desiredFacing is equal to facing or directly behind facing we treat it as being anticlockwise + /// If desiredFacing is equal to facing or directly behind facing we treat it as being anticlockwise. /// public static int GetTurnDirection(WAngle facing, WAngle desiredFacing) { @@ -75,7 +75,7 @@ namespace OpenRA.Mods.Common } /// - /// Returns the remainder angle after rounding to the nearest whole step / facing + /// Returns the remainder angle after rounding to the nearest whole step / facing. /// public static WAngle AngleDiffToStep(WAngle facing, int numFrames) { @@ -97,7 +97,7 @@ namespace OpenRA.Mods.Common return new WAngle(IndexFacing(facing, facings) * (1024 / facings)); } - /// Wraps an arbitrary integer facing value into the range 0 - 255 + /// Wraps an arbitrary integer facing value into the range 0 - 255. public static int NormalizeFacing(int f) { if (f >= 0) diff --git a/OpenRA.Mods.Common/UtilityCommands/Utilities.cs b/OpenRA.Mods.Common/UtilityCommands/Utilities.cs index e2ecdf5554..f9d42341f8 100644 --- a/OpenRA.Mods.Common/UtilityCommands/Utilities.cs +++ b/OpenRA.Mods.Common/UtilityCommands/Utilities.cs @@ -18,7 +18,6 @@ namespace OpenRA.Mods.Common.UtilityCommands { public static class Utilities { - /// Thrown if manifestPropertySelector is null. public static MiniYamlNode GetTopLevelNodeByKey(ModData modData, string key, Func manifestPropertySelector, Func mapPropertySelector = null, diff --git a/OpenRA.Mods.Common/Widgets/Logic/Ingame/CommandBarLogic.cs b/OpenRA.Mods.Common/Widgets/Logic/Ingame/CommandBarLogic.cs index cf0526204b..22e8c82f91 100644 --- a/OpenRA.Mods.Common/Widgets/Logic/Ingame/CommandBarLogic.cs +++ b/OpenRA.Mods.Common/Widgets/Logic/Ingame/CommandBarLogic.cs @@ -19,7 +19,7 @@ using OpenRA.Widgets; namespace OpenRA.Mods.Common.Widgets { - /// Contains all functions that are unit-specific. + /// Contains all functions that are unit-specific. public class CommandBarLogic : ChromeLogic { readonly World world; diff --git a/OpenRA.Mods.Common/WorldExtensions.cs b/OpenRA.Mods.Common/WorldExtensions.cs index a6a309be93..b5d0791adf 100644 --- a/OpenRA.Mods.Common/WorldExtensions.cs +++ b/OpenRA.Mods.Common/WorldExtensions.cs @@ -21,12 +21,12 @@ namespace OpenRA.Mods.Common /// Finds all the actors of which their health radius is intersected by a line (with a definable width) between two points. /// /// The engine world the line intersection is to be done in. - /// The position the line should start at - /// The position the line should end at - /// How close an actor's health radius needs to be to the line to be considered 'intersected' by the line + /// The position the line should start at. + /// The position the line should end at. + /// How close an actor's health radius needs to be to the line to be considered 'intersected' by the line. /// If set, only considers the size of actors that have an /// trait which may improve search performance. However does NOT filter the returned actors on this trait. - /// A list of all the actors intersected by the line + /// A list of all the actors intersected by the line. public static IEnumerable FindActorsOnLine(this World world, WPos lineStart, WPos lineEnd, WDist lineWidth, bool onlyBlockers = false) { // This line intersection check is done by first just finding all actors within a square that starts at the source, and ends at the target. @@ -84,10 +84,10 @@ namespace OpenRA.Mods.Common /// /// Find the point (D) on a line (A-B) that is closest to the target point (C). /// - /// The source point (tail) of the line - /// The target point (head) of the line - /// The target point that the minimum distance should be found to - /// The WPos that is the point on the line that is closest to the target point + /// The source point (tail) of the line. + /// The target point (head) of the line. + /// The target point that the minimum distance should be found to. + /// The WPos that is the point on the line that is closest to the target point. public static WPos MinimumPointLineProjection(this WPos lineStart, WPos lineEnd, WPos point) { var squaredLength = (lineEnd - lineStart).HorizontalLengthSquared;