Greatly improve documentation for methods and their return types (#270)

* Copy over all the return type info

* Add comment for @link constants

* Revert listing bodypart constants

* Revert changes of return type to keep this pr pure

* Revert listing `DepositConstant`

---------

Co-authored-by: Mofeng <[email protected]>

Author: tiennou

dist/index.d.ts

@@ -1,10 +1,18 @@
 /**
  * A site of a structure which is currently under construction.
+ *
+ * A construction site can be created using the 'Construct' button at the left of the game field or the {@link Room.createConstructionSite} method.
+ *
+ * To build a structure on the construction site, give a worker creep some amount of energy and perform {@link Creep.build} action.
+ *
+ * You can remove enemy construction sites by moving a creep on it.
  */
 interface ConstructionSite<T extends BuildableStructureConstant = BuildableStructureConstant> extends RoomObject {
     readonly prototype: ConstructionSite;
     /**
-     * A unique object identifier. You can use `Game.getObjectById` method to retrieve an object instance by its `id`.
+     * A unique object identifier.
+     *
+     * You can use {@link Game.getObjectById} to retrieve an object instance by its `id`.
      */
     id: Id<this>;
     /**
@@ -24,7 +32,7 @@ interface ConstructionSite<T extends BuildableStructureConstant = BuildableStruc
      */
     progressTotal: number;
     /**
-     * One of the `STRUCTURE_*` constants.
+     * One of the {@link StructureConstant STRUCTURE_*} constants.
      */
     structureType: T;
     /**

src/construction-site.ts

@@ -1,20 +1,28 @@
 /**
  * A rare resource deposit needed for producing commodities.
- * Can be harvested by creeps with a WORK body part.
- * Each harvest operation triggers a cooldown period, which becomes longer and longer over time.
+ *
+ * Can be harvested by creeps with a WORK body part. Each harvest operation triggers a cooldown period, which becomes longer and longer over time.
+ *
+ * Learn more about deposits from [this article](https://docs.screeps.com/resources.html).
+ *
+ * |              |             |
+ * | ------------ | ----------- |
+ * | **Cooldown** | 0.001 * totalHarvested ^ 1.2
+ * | **Decay**    | 50,000 ticks after appearing or last harvest operation
  */
 interface Deposit extends RoomObject {
     /**
-     * A unique object identificator.
-     * You can use {@link Game.getObjectById} method to retrieve an object instance by its id.
+     * A unique object identifier.
+     *
+     * You can use {@link Game.getObjectById} to retrieve an object instance by its id.
      */
     id: Id<this>;
     /**
-     * The deposit type, one of the following constants:
-     * * `RESOURCE_MIST`
-     * * `RESOURCE_BIOMASS`
-     * * `RESOURCE_METAL`
-     * * `RESOURCE_SILICON`
+     * The deposit type, one of the {@link DepositConstant}:
+     * - `RESOURCE_MIST`
+     * - `RESOURCE_BIOMASS`
+     * - `RESOURCE_METAL`
+     * - `RESOURCE_SILICON`
      */
     depositType: DepositConstant;
     /**

src/creep.ts

@@ -1,27 +1,31 @@
 /**
- * A flag. Flags can be used to mark particular spots in a room. Flags are visible to their owners only.
+ * A flag.
+ *
+ * Flags can be used to mark particular spots in a room. Flags are visible to their owners only. You cannot have more than 10,000 flags.
  */
 interface Flag extends RoomObject {
     readonly prototype: Flag;
 
     /**
-     * Flag color. One of the `COLOR_*` constants.
+     * Flag color. One of the {@link ColorConstant COLOR_*} constants.
      */
     color: ColorConstant;
     /**
+     * The flag's memory.
+     *
      * A shorthand to Memory.flags[flag.name]. You can use it for quick access the flag's specific memory data object.
      */
     memory: FlagMemory;
     /**
-     * Flag’s name.
+     * The flag’s name.
      *
      * You can choose the name while creating a new flag, and it cannot be changed later.
      *
-     * This name is a hash key to access the flag via the `Game.flags` object. The maximum name length is 60 characters.
+     * This name is a hash key to access the flag via the {@link Game.flags} object. The maximum name length is 60 characters.
      */
     name: string;
     /**
-     * Flag secondary color. One of the `COLOR_*` constants.
+     * Flag secondary color. One of the {@link ColorConstant COLOR_*} constants.
      */
     secondaryColor: ColorConstant;
     /**
@@ -31,22 +35,28 @@ interface Flag extends RoomObject {
     remove(): OK;
     /**
      * Set new color of the flag.
-     * @param color One of the following constants: COLOR_WHITE, COLOR_GREY, COLOR_RED, COLOR_PURPLE, COLOR_BLUE, COLOR_CYAN, COLOR_GREEN, COLOR_YELLOW, COLOR_ORANGE, COLOR_BROWN
-     * @parma secondaryColor Secondary color of the flag. One of the COLOR_* constants.
-     * @returns Result Code: OK, ERR_INVALID_ARGS
+     * @param color One of the {@link ColorConstant COLOR_*} constants.
+     * @param secondaryColor Secondary color of the flag. One of the {@link ColorConstant COLOR_*} constants.
+     * @returns One of the following codes:
+     * - OK: The operation has been scheduled successfully.
+     * - ERR_INVALID_ARGS: color or secondaryColor is not a valid color constant.
      */
     setColor(color: ColorConstant, secondaryColor?: ColorConstant): OK | ERR_INVALID_ARGS;
     /**
      * Set new position of the flag.
      * @param x The X position in the room.
      * @param y The Y position in the room.
-     * @returns Result Code: OK, ERR_INVALID_TARGET
+     * @returns One of the following codes:
+     * - OK: The operation has been scheduled successfully.
+     * - ERR_INVALID_TARGET: The target provided is invalid.
      */
     setPosition(x: number, y: number): OK | ERR_INVALID_ARGS;
     /**
      * Set new position of the flag.
-     * @param pos Can be a RoomPosition object or any object containing RoomPosition.
-     * @returns Result Code: OK, ERR_INVALID_TARGET
+     * @param pos Can be a {@link RoomPosition} object or any object containing RoomPosition.
+     * @returns One of the following codes:
+     * - OK: The operation has been scheduled successfully.
+     * - ERR_INVALID_TARGET: The target provided is invalid.
      */
     setPosition(pos: RoomPosition | { pos: RoomPosition }): OK | ERR_INVALID_ARGS;
 }

src/deposit.ts

@@ -31,15 +31,20 @@ interface Game {
      */
     market: Market;
     /**
-     * A hash containing all your power creeps with their names as hash keys. Even power creeps not spawned in the world can be accessed here.
+     * A hash containing all your power creeps with their names as hash keys.
+     *
+     * Even power creeps not spawned in the world can be accessed here.
      */
     powerCreeps: { [creepName: string]: PowerCreep };
     /**
-     * An object with your global resources that are bound to the account, like pixels or cpu unlocks. Each object key is a resource constant, values are resources amounts.
+     * An object with your global resources that are bound to the account, like pixels or cpu unlocks.
+     *
+     * Each object key is a resource constant, values are resources amounts.
      */
     resources: { [key: string]: any };
     /**
      * A hash containing all the rooms available to you with room names as hash keys.
+     *
      * A room is visible if you have a creep or an owned structure in it.
      */
     rooms: { [roomName: string]: Room };
@@ -63,12 +68,16 @@ interface Game {
     shard: Shard;
 
     /**
-     * System game tick counter. It is automatically incremented on every tick.
+     * System game tick counter.
+     *
+     * It is automatically incremented on every tick.
      */
     time: number;
 
     /**
-     * Get an object with the specified unique ID. It may be a game object of any type. Only objects from the rooms which are visible to you can be accessed.
+     * Get an object with the specified unique ID.
+     *
+     * It may be a game object of any type. Only objects from the rooms which are visible to you can be accessed.
      * @param id The unique identifier.
      * @returns an object instance or null if it cannot be found.
      */
@@ -80,12 +89,15 @@ interface Game {
      *
      * This way, you can set up notifications to yourself on any occasion within the game.
      *
-     * You can schedule up to 20 notifications during one game tick. Not available in the Simulation Room.
+     * You can schedule up to 20 notifications during one game tick. Not available in the Simulator.
      * @param message Custom text which will be sent in the message. Maximum length is 1000 characters.
      * @param groupInterval If set to 0 (default), the notification will be scheduled immediately.
      * Otherwise, it will be grouped with other notifications and mailed out later using the specified time in minutes.
+     * @returns One of the following codes:
+     * - OK: The message has been sent successfully.
+     * - ERR_FULL: More than 20 notifications sent this tick.
      */
-    notify(message: string, groupInterval?: number): undefined;
+    notify(message: string, groupInterval?: number): OK | ERR_FULL;
 }
 
 declare var Game: Game;