Feature/code clean up #603
Conversation
…s and `AiTick` event handling.
…and readability.
…ion/annotations for clarity
…e documentation for better clarity and detail.
…improved code understanding and maintainability.
There was a problem hiding this comment.
Documentation should provide clarity or additional information that isn't already obvious from the code itself e.g. why it was built the way it was, how it should be used etc...
A lot of these, presumably ai generated, comments are summaries of what the code already says, not providing any extra info and actively making it harder to comprehend or find out information out as reader (who doesn't have a million token context length).
I've marked a few examples of ones that aren't useful and why.
One of the places documentation summaries are useful however, is at a class level. A sentence or two explaining what a class does, so a reader can quickly understand without having to read a hundred lines of code would be far more useful. (And a lot easier to review)
I would caution overriding existing descriptions, and certainly no @params.
| * @param E The type of elements held in this queue. | ||
| * @param capacity The maximum number of elements the queue can hold. |
| * @param players The collection of active players in the game world. | ||
| * @param npcs The collection of non-player characters (NPCs) in the game world. | ||
| * @param items The collection of floor items available in the game world. | ||
| * @param objects The collection of objects in the game world. | ||
| * @param itemDefinitions Definitions and metadata describing all game items. | ||
| * @param objectDefinitions Definitions and metadata describing all game objects. | ||
| * @param npcDefinitions Definitions and metadata describing all NPCs. | ||
| * @param interfaceDefinitions Definitions for user interfaces within the game. | ||
| * @param handler Interface handler for user interaction with game interface elements. |
| /** | ||
| * Represents a handler for managing interactions with floor items in the game. | ||
| * The variable encapsulates a FloorItemOptionHandler which provides functionality | ||
| * to handle specific options or actions related to items located on the ground. | ||
| * It operates on a list of items that can be interacted with directly from the game floor. | ||
| */ | ||
| private val interactFloorItem = FloorItemOptionHandler(items) | ||
| /** | ||
| * A private instance of DialogueContinueHandler used to manage and control the continuation of dialogue interactions. | ||
| * It leverages interfaceDefinitions to handle specific interaction rules or configurations. | ||
| */ | ||
| private val interactDialogue = DialogueContinueHandler(interfaceDefinitions) | ||
| /** | ||
| * This variable represents an instance of InterfaceClosedHandler | ||
| * that is used to handle the closure of an interface. It encapsulates | ||
| * logic or actions to be performed when the interface is closed. | ||
| */ |
| /** | ||
| * Logger used for recording debug and error messages related to the processing | ||
| * of player instructions in the `InstructionTask` class. Provides inline logging | ||
| * capabilities for better performance and structured output. | ||
| */ |
There was a problem hiding this comment.
No need to explain what a logger is.
| /** | ||
| * Companion object for the `Catch` class. | ||
| * Provides utility methods and properties for handling instances of the `Catch` class. | ||
| */ |
There was a problem hiding this comment.
Companions don't ever need descriptions
| * @param public The public status of the player. Expected values are: | ||
| * "friends", "off", "hide", or other values default to 0. | ||
| * @param trade The trade status of the player. Expected values are: | ||
| * "friends", "off", or other values default to 0. |
There was a problem hiding this comment.
Misses context as to what 0 means - "on"
| /** | ||
| * Retrieves the area associated with the given name. | ||
| * | ||
| * @param name The name of the area to retrieve. | ||
| * @return The area corresponding to the provided name, or an empty area if the name is not found. | ||
| */ |
| * The `AmmoDefinitions` class is responsible for decoding and managing a collection of ammo definitions. | ||
| * It inherits from `DefinitionsDecoder` with a specific type of `AmmoDefinition`. |
There was a problem hiding this comment.
Loses all the useful information of the existing comment and isn't using Kotlin doc syntax
| * Represents a collection of area definitions, which can be accessed based on various keys such as | ||
| * name, tags, or zones. This class centralizes the management and retrieval of area definitions, | ||
| * allowing for efficient queries and lookups. |
| * @param text The content of the message that will be sent. | ||
| * @param type The type of chat message to display, default is ChatType.Game. | ||
| * @param tile The tile ID associated with the message, default is 0. | ||
| * @param name Optional name associated with the message, default is null. |
There was a problem hiding this comment.
These param descriptions are better than the original, but arguably neither should exist.
No description provided.