dooooooooooocs

TrinketTinker/Companions/Motions/BounceMotion.cs

@@ -12,6 +12,7 @@ public sealed class BounceMotion(TrinketTinkerCompanion companion, MotionData da
         /// <summary>trig function input</summary>
         private double theta = 0f;
 
+        /// <inheritdoc/>
         public override void UpdateLocal(GameTime time, GameLocation location)
         {
             base.UpdateLocal(time, location);
@@ -23,6 +24,7 @@ public override void UpdateLocal(GameTime time, GameLocation location)
                 theta = 0f;
         }
 
+        /// <inheritdoc/>
         public override void Draw(SpriteBatch b)
         {
             float thetaF = args.Squash ? (float)Math.Max(Math.Pow(Math.Cos(2 * Math.PI * theta), 5) / 2, 0) : 0;

TrinketTinker/Companions/Motions/HoverMotion.cs

@@ -11,12 +11,14 @@ public sealed class HoverMotion : BaseLerpMotion<HoverArgs>
         /// <summary>trig function input</summary>
         private double theta = 0f;
 
+        /// <inheritdoc/>
         public HoverMotion(TrinketTinkerCompanion companion, MotionData data) : base(companion, data)
         {
             motionOffset.Y -= 128f;
             c.Offset = motionOffset;
         }
 
+        /// <inheritdoc/>
         public override void UpdateLocal(GameTime time, GameLocation location)
         {
             base.UpdateLocal(time, location);

TrinketTinker/Companions/Motions/IMotion.cs

@@ -6,12 +6,34 @@ namespace TrinketTinker.Companions.Motions
 {
     public interface IMotion
     {
+        /// <summary>Initialize motion, setup lightsource if needed.</summary>
+        /// <param name="farmer"></param>
         void Initialize(Farmer farmer);
+
+        /// <summary>Cleanup motion, remove lightsource.</summary>
+        /// <param name="farmer"></param>
         void Cleanup();
+
+        /// <summary>Update info that should change every tick, for all game instances in multiplayer.</summary>
+        /// <param name="time"></param>
+        /// <param name="location"></param>
+        void UpdateGlobal(GameTime time, GameLocation location);
+
+        /// <summary>Update info that should change every tick, for owner only. Netfield changes should happen here.</summary>
+        /// <param name="time"></param>
+        /// <param name="location"></param>
+        void UpdateLocal(GameTime time, GameLocation location);
+
+        /// <summary>Draws the companion, for all game instances in multiplayer.</summary>
+        /// <param name="b"></param>
         void Draw(SpriteBatch b);
+
+        /// <summary>Update light source when owner changes location</summary>
         void OnOwnerWarp();
+
+        /// <summary>Changes the position of the anchor that the companion moves relative to.</summary>
+        /// <param name="time"></param>
+        /// <param name="location"></param>
         void UpdateAnchor(GameTime time, GameLocation location);
-        void UpdateGlobal(GameTime time, GameLocation location);
-        void UpdateLocal(GameTime time, GameLocation location);
     }
 }

TrinketTinker/Companions/Motions/LerpMotion.cs

@@ -11,12 +11,14 @@ public class BaseLerpMotion<IArgs> : Motion<IArgs> where IArgs : LerpArgs
         /// <summary>Variable for how much interpolation happened so far.</summary>
         private float lerp = -1f;
 
+        /// <inheritdoc/>
         public BaseLerpMotion(TrinketTinkerCompanion companion, MotionData data) : base(companion, data)
         {
             motionOffset.Y -= c.Sprite.SpriteHeight * 4 / 2;
             c.Offset = motionOffset;
         }
 
+        /// <inheritdoc/>
         public override void UpdateLocal(GameTime time, GameLocation location)
         {
             if (lerp < 0f || AnchorChanged)

TrinketTinker/Companions/Motions/Motion.cs

@@ -29,7 +29,7 @@ public abstract class Motion<TArgs> : IMotion where TArgs : IArgs
         /// <summary>Anchor changed during this tick</summary>s
         protected bool AnchorChanged => prevAnchorTarget != currAnchorTarget;
 
-        /// <summary>Constructor</summary>
+        /// <summary>Basic constructor, tries to parse arguments as the generic <see cref="IArgs"/> type.</summary>
         /// <param name="companion"></param>
         /// <param name="data"></param>
         public Motion(TrinketTinkerCompanion companion, MotionData data)
@@ -47,8 +47,7 @@ public Motion(TrinketTinkerCompanion companion, MotionData data)
             c.Offset = motionOffset;
         }
 
-        /// <summary>Initialize motion, setup lightsource if needed.</summary>
-        /// <param name="farmer"></param>
+        /// <inheritdoc/>
         public virtual void Initialize(Farmer farmer)
         {
             if (d.LightRadius > 0)
@@ -58,8 +57,7 @@ public virtual void Initialize(Farmer farmer)
             }
         }
 
-        /// <summary>Initialize motion, remove lightsource.</summary>
-        /// <param name="farmer"></param>
+        /// <inheritdoc/>
         public virtual void Cleanup()
         {
             if (d.LightRadius > 0)
@@ -68,9 +66,7 @@ public virtual void Cleanup()
             }
         }
 
-        /// <summary>Make a new light source on warp.</summary>
-        /// <param name="farmer"></param>
-        /// 
+        /// <inheritdoc/>
         public virtual void OnOwnerWarp()
         {
             if (d.LightRadius > 0)
@@ -79,6 +75,9 @@ public virtual void OnOwnerWarp()
             }
         }
 
+        /// <summary>Changes the position of the anchor that the companion moves relative to, based on <see cref="MotionData.Anchors"/>.</summary>
+        /// <param name="time"></param>
+        /// <param name="location"></param>
         public virtual void UpdateAnchor(GameTime time, GameLocation location)
         {
             prevAnchorTarget = currAnchorTarget;
@@ -110,14 +109,10 @@ public virtual void UpdateAnchor(GameTime time, GameLocation location)
 
         }
 
-        /// <summary>Update for the client of the player that equipped this trinket, responsible for netfields.</summary>
-        /// <param name="time">Game time</param>
-        /// <param name="location">Current map location</param>
+        /// <inheritdoc/>
         public abstract void UpdateLocal(GameTime time, GameLocation location);
 
-        /// <summary>Update for all clients, responsible for animation frame.</summary>
-        /// <param name="time">Game time</param>
-        /// <param name="location">Current map location</param>
+        /// <inheritdoc/>
         public virtual void UpdateGlobal(GameTime time, GameLocation location)
         {
             if (d.AlwaysMoving || c.Moving)
@@ -126,7 +121,7 @@ public virtual void UpdateGlobal(GameTime time, GameLocation location)
                 switch (d.LoopMode)
                 {
                     case LoopMode.PingPong:
-                        isReverse = c.Sprite.AnimatePingPong(time, frameStart, d.AnimationFrameLength, d.Interval, isReverse);
+                        c.Sprite.AnimatePingPong(time, frameStart, d.AnimationFrameLength, d.Interval, ref isReverse);
                         break;
                     case LoopMode.Standard:
                         c.Sprite.Animate(time, frameStart, d.AnimationFrameLength, d.Interval);
@@ -142,8 +137,7 @@ public virtual void UpdateGlobal(GameTime time, GameLocation location)
                 Utility.repositionLightSource(lightId, c.Position + c.Offset);
         }
 
-        /// <summary>Draw the companion.</summary>
-        /// <param name="b">SpriteBatch</param>
+        /// <inheritdoc/>
         public virtual void Draw(SpriteBatch b)
         {
             // float shadowScale = 3f * Utility.Lerp(1f, 0.8f, Math.Max(1f, -c.Offset.Y / 12));
@@ -247,6 +241,10 @@ protected virtual int DirectionFrameStart()
             return (Math.Abs(c.direction.Value) - 1) * d.AnimationFrameLength + d.AnimationFrameStart;
         }
 
+        /// <summary>Helper function, check if the sprite collides with anything.</summary>
+        /// <param name="location"></param>
+        /// <param name="spritePosition"></param>
+        /// <returns></returns>
         protected virtual bool CheckSpriteCollsion(GameLocation location, Vector2 spritePosition)
         {
             return location.isCollidingPosition(

TrinketTinker/Companions/Motions/OrbitMotion.cs

@@ -16,6 +16,7 @@ public class OrbitMotion : BaseStaticMotion<OrbitArgs>
         /// <summary>trig function input</summary>
         protected readonly float radiusY = 40f;
 
+        /// <inheritdoc/>
         public OrbitMotion(TrinketTinkerCompanion companion, MotionData data) : base(companion, data)
         {
             motionOffset.Y -= 64f;
@@ -24,6 +25,11 @@ public OrbitMotion(TrinketTinkerCompanion companion, MotionData data) : base(com
             radiusY = args?.RadiusY ?? radiusY;
         }
 
+        /// <summary>
+        /// Calculates circular motion using cos for x and sin for y
+        /// </summary>
+        /// <param name="time"></param>
+        /// <param name="location"></param>
         public override void UpdateLocal(GameTime time, GameLocation location)
         {
             base.UpdateLocal(time, location);
@@ -33,6 +39,8 @@ public override void UpdateLocal(GameTime time, GameLocation location)
             if (theta >= 2f)
                 theta = 0f;
         }
+
+        /// <inheritdoc/>
         public override void Draw(SpriteBatch b)
         {
             DrawWithShadow(

TrinketTinker/Constants.cs

@@ -5,8 +5,8 @@ namespace TrinketTinker
 {
     public static class Constants
     {
-        /// <summary>Float second of 1 frame (60fps), not accurate since it is float, only use for bounds.</summary>
-        public const float ONE_FRAME = 1000 / 60;
+        /// <summary>Float second of 1 frame (60fps), not perfectly accurate since it is float, only use for bounds.</summary>
+        public const float ONE_FRAME = 1000f / 60;
 
         /// <summary>Special color name for the animated prismatic color mask.</summary>
         public const string COLOR_PRISMATIC = "Prismatic";

TrinketTinker/Effects/Abilities/Ability.cs

@@ -16,7 +16,7 @@ public abstract class Ability<TArgs> : IAbility where TArgs : IArgs
         protected readonly AbilityData d;
         /// <summary>Ability name, default to type name.</summary>
         public readonly string Name;
-        /// <summary>True if trinket data produces a valid ability.</summary>
+        /// <inheritdoc/>
         public bool Valid { get; set; } = false;
         /// <summary>True if trinket equiped.</summary>
         protected bool Active { get; set; }
@@ -27,7 +27,7 @@ public abstract class Ability<TArgs> : IAbility where TArgs : IArgs
         /// <summary>Class dependent arguments for subclasses</summary>
         protected readonly TArgs args;
 
-        /// <summary>Constructor</summary>
+        /// <summary>Basic constructor, tries to parse arguments as the generic <see cref="IArgs"/> type.</summary>
         /// <param name="effect"></param>
         /// <param name="data"></param>
 #pragma warning disable CS8618 // Non-nullable field must contain a non-null value when exiting constructor. Consider adding the 'required' modifier or declaring as nullable.
@@ -163,6 +163,8 @@ protected virtual void HandleProc(object? sender, ProcEventArgs args)
             }
         }
 
+        /// <summary>Get where the on proc <see cref="TemporaryAnimatedSprite"/> should be drawn from.</summary>
+        /// <returns></returns>
         protected virtual Vector2 GetTASPosition()
         {
             return e.CompanionAnchor;

TrinketTinker/Effects/Abilities/DebugDummyAbility.cs

@@ -9,7 +9,7 @@ namespace TrinketTinker.Effects.Abilities
     /// <summary>Prints many logs, doesn't do anything else.</summary>
     public sealed class DebugDummyAbility(TrinketTinkerEffect effect, AbilityData data, int lvl) : Ability<NoArgs>(effect, data, lvl)
     {
-        /// <summary>Debug log.</summary>
+        /// <summary>Print debug log.</summary>
         /// <param name="proc"></param>
         /// <returns></returns>
         protected override bool ApplyEffect(ProcEventArgs proc)

TrinketTinker/Effects/Abilities/HitscanAbility.cs

@@ -6,6 +6,12 @@
 
 namespace TrinketTinker.Effects.Abilities
 {
+    /// <summary>
+    /// Deal damage to monster within range, optionally stun them for a period.
+    /// </summary>
+    /// <param name="effect"></param>
+    /// <param name="data"></param>
+    /// <param name="lvl"></param>
     public sealed class HitscanAbility(TrinketTinkerEffect effect, AbilityData data, int lvl) : Ability<DamageArgs>(effect, data, lvl)
     {
         protected override bool ApplyEffect(ProcEventArgs proc)

TrinketTinker/Effects/Abilities/IAbility.cs

@@ -5,10 +5,23 @@ namespace TrinketTinker.Effects.Abilities
 {
     public interface IAbility
     {
+        /// <summary>Mark the new ability as valid, if false after constructor the ability is discarded</summary>
         bool Valid { get; }
 
+        /// <summary>Activate the ability by registering events.</summary>
+        /// <param name="farmer"></param>
+        /// <returns></returns>
         bool Activate(Farmer farmer);
+
+        /// <summary>Deactivate the ability by unregistering events.</summary>
+        /// <param name="farmer"></param>
+        /// <returns></returns>
         bool Deactivate(Farmer farmer);
+
+        /// <summary>Perform update every tick.</summary>
+        /// <param name="farmer"></param>
+        /// <param name="time"></param>
+        /// <param name="location"></param>
         void Update(Farmer farmer, GameTime time, GameLocation location);
     }
 }

TrinketTinker/Effects/Abilities/ProjectileAbility.cs

@@ -8,6 +8,12 @@
 
 namespace TrinketTinker.Effects.Abilities
 {
+    /// <summary>
+    /// Shoot a projectile that deals damage to monster within range, optionally stun them for a period.
+    /// </summary>
+    /// <param name="effect"></param>
+    /// <param name="data"></param>
+    /// <param name="lvl"></param>
     public sealed class ProjectileAbility(TrinketTinkerEffect effect, AbilityData data, int lvl) : Ability<ProjectileArgs>(effect, data, lvl)
     {
         protected override bool ApplyEffect(ProcEventArgs proc)

TrinketTinker/Effects/Abilities/TriggerAbility.cs

@@ -1,5 +1,3 @@
-using Microsoft.Xna.Framework;
-using StardewValley;
 using StardewValley.Triggers;
 using TrinketTinker.Effects.Proc;
 using TrinketTinker.Models;

TrinketTinker/Effects/Pewpew/TinkerProjectile.cs

@@ -10,6 +10,9 @@
 
 namespace TrinketTinker.Effects.Pewpew
 {
+    /// <summary>
+    /// Custom projectile class, can utilize custom texture and deal damage with optional knockback crit/crit damage and stun.
+    /// </summary>
     public class TinkerProjectile : Projectile
     {
 

TrinketTinker/Effects/Proc/ProcEventArgs.cs

@@ -6,23 +6,41 @@
 
 namespace TrinketTinker.Effects.Proc
 {
-    /// <summary>Proc event data</summary>
+    /// <summary>
+    /// Proc event data.
+    /// Most properties are only set for specific kinds of proc.
+    /// </summary>
     public class ProcEventArgs(ProcOn procOn, Farmer farmer) : EventArgs
     {
-        /// <summary>Kind of proc triggering this event <see cref="ProcOn"/></summary>
+        /// <summary>Kind of proc triggering this event</summary>
         public ProcOn ProcOn => procOn;
+        /// <summary>Player who triggered the event</summary>
         public Farmer Farmer => farmer;
+        /// <summary>Game time</summary>
         public GameTime? Time { get; set; } = null;
+        /// <summary>Proc location, one of the backing props of <see cref="LocationOrCurrent"/></summary>
         public GameLocation? Location { get; set; } = null;
+        /// <summary>Target monster</summary>
         public Monster? Monster { get; set; } = null;
+        /// <summary>Damage amount, to monster or to player</summary>
         public int? DamageAmount { get; set; } = null;
+        /// <summary>Whether damage (to monster) was a bomb</summary>
         public bool? IsBomb { get; set; } = null;
+        /// <summary>Whether damage (to monster) was a critical hit</summary>
         public bool? IsCriticalHit { get; set; } = null;
+        /// <summary>Arguments given to trigger action handler.</summary>
         public string[]? TriggerArgs { get; set; } = null;
+        /// <summary>Trigger action context</summary>
         public TriggerActionContext? TriggerContext { get; set; } = null;
-        public GameLocation LocationOrCurrent => Location ?? Farmer?.currentLocation ?? Game1.currentLocation;
+        /// <summary>Get the most valid location of this proc, either the event location or the player's current location</summary>
+        public GameLocation LocationOrCurrent => Location ?? Farmer.currentLocation;
 
-        public bool Check(AbilityData data)
+        /// <summary>
+        /// Validate whether this proc should trigger ability of given data.
+        /// </summary>
+        /// <param name="data"></param>
+        /// <returns></returns>
+        internal bool Check(AbilityData data)
         {
             if (Farmer == null)
                 return false;

TrinketTinker/Extensions.cs

@@ -9,14 +9,13 @@ public static class Extensions
         /// Reverse the animation from last frame, e.g. 1 2 3 4 3 2 1 2 3 4.
         /// Ignores <see cref="AnimatedSprite.loop"/>.
         /// </summary>
-        /// <param name="s"></param>
-        /// <param name="gameTime"></param>
-        /// <param name="startFrame"></param>
-        /// <param name="numberOfFrames"></param>
-        /// <param name="interval"></param>
-        /// <param name="isReverse">True if animation is going backwards</param>
-        /// <returns>Updated isReverse flag</returns>
-        public static bool AnimatePingPong(this AnimatedSprite s, GameTime gameTime, int startFrame, int numberOfFrames, float interval, bool isReverse)
+        /// <param name="s">animated sprite</param>
+        /// <param name="gameTime">game time object from update</param>
+        /// <param name="startFrame">initial frame</param>
+        /// <param name="numberOfFrames">length of animation</param>
+        /// <param name="interval">milisecond interval between frames</param>
+        /// <param name="isReverse">flag for whether animation is going forward or backwards, will be updated in this method.</param>
+        public static void AnimatePingPong(this AnimatedSprite s, GameTime gameTime, int startFrame, int numberOfFrames, float interval, ref bool isReverse)
         {
             int lastFrame;
             int step;
@@ -45,7 +44,6 @@ public static bool AnimatePingPong(this AnimatedSprite s, GameTime gameTime, int
                 }
             }
             s.UpdateSourceRect();
-            return isReverse;
         }
     }
 }