Fixed up documentation for comments.md and linting.md

Comments.md added info pertaining to Kev's review
linting.md i just stopped spouting misinformation

docs/comments.md

@@ -1,37 +1,46 @@
 # Commenting code
 
-People spend more time reading code than writing it (sometimes substantially more so). As such, comments and documentation are **vital** for any large codebase like this.
+People spend more time reading code than writing it (sometimes substantially more so). As such, comments and documentation are **vital** for any large codebase like this to function.
 
 ## While we're not enforcing a strict standard, here are some things to keep in mind:
 - Make comments meaningful
-  - Comments should explain _why_ a line or block of code exists - its "raison d'être", if you will.
+  - Comments should **NOT** repeat _what_ code _does_[^1] or explain concepts obvious to someone with a basic understanding of the language at hand. Instead, focus on explaining _why_ a line or block of code exists - its "raison d'être", if you will.
-  - Comments should not repeat chunks of code or explain concepts obvious to the average reader like the meaning of `&&=` or `??`
+    - Anyone with basic reading comprehension and a good IDE can figure out what code does; gaining a _post hoc_ understanding of the _reasons_ behind its existence takes a lot more digging, effort and bloodshed.
-- Make comments readable
+- Keep comments readable
-  - The length of a comment should roughly scale with the complexity of whatever it is describing. Small quips are fine for inline comments and explanations, but summarizing a 300 line function with "Starts a battle" is about as good as doing nothing.
+  - A comment's verbosity should roughly scale with the complexity of its subject matter. Some people naturally write shorter or longer comments as a personal style, but summarizing a 300 line function with "does a thing" is about as good as writing nothing. Conversely, writing a paragraph-level response where a basic one-liner would suffice is equally unhelpful.
-  - Long comments should ideally be broken into multiple lines at around the 100-120 character mark.
+  - Long comments should ideally be broken into multiple lines at around the 100-120 character mark. This isn't _mandatory_, but avoids unnecessary scrolling in terminals and IDEs.
 - Make sure comments exist on Functions, Classes, Methods, and Properties
   - These may be the most important things to comment. When someone goes to use a function/class/method/etc., having a comment reduces the need to flip back and forth between files to figure out what XYZ does. Peek Definition is great until you're three nested levels deep.
-  - The best example of this is TSDoc-style comments as seen below:
-    - When formatted this way, the comment gets shown within VS Code or similar IDEs just by hovering over the function!
-    - Functions also show the comment for each parameter as you type them, making keeping track of arguments inside lengthy functions much more clear.
 
+[^1]: With exceptions for extremely long, convoluted or unintuitive methods (though an over-dependency on said comments is likely asymptomatic of poorly structured code).
+
+Given all this, look at the following
+
+# TSDoc
+Taking all these together, one notable example of good comments are those adhering to the TSDoc standard. These comments (frequentl)
+When formatted this way, these comments are shown within VS Code or similar IDEs just by hovering over the function!
+- Functions also show the comment for each parameter as you type them, making keeping track of arguments inside lengthy functions much more clear.
+
+## Syntax
+For an example of how TSDoc comments work, here are several real examples of TSDoc comments at work, taken from various files inside this very repo[^2]:
 ```ts
 /**
  * Change the type-based weather modifier if this move's power would be reduced by it.
  * @param user - The {@linkcode Pokemon} using this move
  * @param target - The {@linkcode Pokemon} being targeted by this move
  * @param move - The {@linkcode Move} being used (unused)
- * @param args - [0]: A {@linkcode NumberHolder} for arenaAttackTypeMultiplier
+ * @param args - [0]: A {@linkcode NumberHolder} for `arenaAttackTypeMultiplier`
  * @returns - Whether the move effect was applied successfully
  */
 apply(user: Pokemon, target: Pokemon, move: Move, args: [NumberHolder, ...any]): boolean {
 }
 
-/** Class containing  */
+/** Class containing configurable user settings. */
 class Settings {
   /** Set to `true` when experimental animated sprites from Gen6+ should be used */
   public experimentalSprites: boolean = false;
 }
+
 /**
  * Cure the user's party of non-volatile status conditions, ie. Heal Bell, Aromatherapy
  */
@@ -39,15 +48,19 @@ export class DontHealThePartyPlsAttr extends MoveAttr {
 }
 
 ```
-You'll notice this contains an `{@linkcode Object}` tag for each parameter. This provides an easy type denomination and hyperlink to that type using VS Code's Intellisense. `@linkcode` is used instead of `@link` so that the text appears in monospace which is more obviously a `type` rather than a random hyperlink.
+
+Looking at the example given, you'll notice this contains an `{@linkcode XYZ}` tag for each parameter. This provides an easy type denomination and hyperlink to that type in most modern IDEs. (`@linkcode` is used here instead of `@link` so that the text appears in monospace which is more obviously a `type` rather than a random hyperlink.) \
+Also note the dashes (` - `) between the parameter names and descriptions - these are **mandatory** under the TSDoc spec[^3].
 
 If you're interested in going more in depth, you can find a reference guide for how comments like these work [here](https://tsdoc.org).
 
+[^3]: Incidentally, this is also the only place dashes are explicitly _required_.
+
 ### What not to do:
 - Don't leave comments for code you don't understand
   - Incorrect information is worse than no information. If you aren't sure how something works, don't make something up to explain it - ask for help and/or mark it as TODO.
 - Don't over-comment
-  - Not everything needs an explanation. Try to summarize blocks of code instead of singular lines where possible. Single line comments should call out specific oddities or features.
+  - Not everything needs a comment. Try to summarize blocks of code instead of singular lines where possible, always preferring giving a reason over stating a fact. Single line comments should call out specific oddities or features.
 
 ## How do Abilities and Moves differ from other classes?
 While other classes should be fully documented, Abilities and Moves heavily incoperate inheritance (i.e. the `extends` keyword). Because of this, much of the functionality in these classes is duplicated or only slightly changed between classes.

docs/linting.md

@@ -41,7 +41,6 @@ A full list of flags and options can be found on [their website](https://biomejs
 
 - `--write` will cause Biome to write all "safe" fixes and formatting changes directly to your files (rather than just complaining and doing nothing).
 - `--changed` and `--staged` will only perform checks on all changed or staged files respectively. Biome sources this info from the relevant version control system (in this case Git).
-- `--only=XXX` will filter reported lint issues to a specific category or rule name. Useful for checking errors after Lefthook flags your code (summary screen doesn't show exact line numbers).
 - `diagnostic-level=XXX` will only show diagnostics with at least the given severity level (`info/warn/error`). Useful to only focus on errors causing a failed workflow run or similar.
 
 ## Linting Rules
@@ -61,4 +60,6 @@ Any questions about linting rules should be brought up in the `#dev-corner` chan
 ## What about ESLint?
 
 <!-- Remove if/when we finally ditch eslint for good -->
-Our project migrated away from ESLint around March 2025 due to it simply not scaling well enough with the codebase's ever-growing size. The [existing eslint rules](../eslint.config.js) are considered _deprecated_, only kept due to Biome lacking the corresponding rules.
+Our project migrated away from ESLint around March 2025 due to it simply not scaling well enough with the codebase's ever-growing size. The [existing eslint rules](../eslint.config.js) are considered _deprecated_, only kept due to Biome lacking the corresponding rules in its current ruleset.
+
+No additional ESLint rules should be added under any circumstances - even the few currently in circulation take longer to run than the entire Biome formatting/linting suite combined.