migrate docs to jsdoc with codemod, not documented are marked as inte…

…rnal

remove api.md for now
fix gentypes

scripts/genTypes.mjs

@@ -3,5 +3,5 @@ import fs from 'fs'
 const targetFile = './dist/types.d.ts';
 let types = fs.readFileSync(targetFile, 'utf8')
 const modules = fs.readdirSync('./dist/lib/modules').filter(f => f !== 'index')
-types = modules.filter(module => module.endsWith('.d.ts')).map(module => `import "./lib/modules/${module}"`).join('\n') + types
+types = modules.filter(module => module.endsWith('.d.ts')).map(module => `import "./lib/modules/${module}"`).join('\n') + '\n' + types
 fs.writeFileSync(targetFile, types, 'utf8')

src/lib/modules/blockUpdates.ts

@@ -167,10 +167,15 @@ export const server = (serv: Server, { version }: Options) => {
 }
 declare global {
   interface Server {
+    /** @internal */
     "MAX_UPDATES_PER_TICK": number
+    /** Trigger a block update for the block in `world` at `pos`. `fromTick` is the current server tick `serv.tickCount`, `tick` is the future server tick when the update should be executed. When `forceNotify` is true, the block update will always trigger an update on the 6 direct neighbors, even when no handler is registered for this block type. `data` is an optional object that will be given to the handler. */
     "updateBlock": (world: any, pos: any, fromTick: any, tick: any, forceNotify?: boolean, data?: null) => void
+    /** Similar to `serv.updateBlock` but will trigger an update on the 6 direct neighbors of `pos` but not on the block itself. */
     "notifyNeighborsOfStateChange": (world: any, pos: any, fromTick: any, tick: any, forceNotify?: boolean, data?: null) => void
+    /** Similar to `serv.updateBlock` but will trigger an update on 5 of the direct neighbors of `pos.plus(dir)`, but not on the block at `pos` or `pos.plus(dir)`. */
     "notifyNeighborsOfStateChangeDirectional": (world: any, pos: any, dir: any, fromTick: any, tick: any, forceNotify?: boolean, data?: null) => void
+    /** Register a handler that will be called when a block of the type `name` is updated. It should verify that the block state is still correct according to the game's rules. It is triggered when a neighboring block has been modified.,    * ,    * The arguments of the handler are the world in which the update occurred, the block, fromTick the tick at which the update was triggered, the tick the update was scheduled to (current tick), and optional data (null most of the time) that can be used to transmit data between block updates. The handler should return true if the block was changed so the update manager can send a multiBlockChange packet for all the changes that occurred within the tick. The state of the block should be modified by using the world's setBlockXXX functions instead of serv.setBlock (that would send redundant updates to players).    */
     "onBlockUpdate": (name: any, handler: any) => void
   }
 }

src/lib/modules/blocks.ts

@@ -105,10 +105,15 @@ export const server = function (serv: Server, { version }: Options) {
 }
 declare global {
   interface Player {
+    /** change the block at position `position` to `blockType` and `blockData`,    * ,    * this will not change the block for the user himself. It is mainly useful when a user places a block,    * and only needs to send it to other players on the server    */
     "changeBlock": (position: any, blockType: any, blockData: any) => Promise<void>
+    /** change the block at position `position` to `blockType` and `blockData`,    * ,    * this will not make any changes on the server's world and only sends it to the user as a "fake" or "local" block    */
     "sendBlock": (position: any, blockStateId: any) => any
+    /** Saves block in world and sends block update to all players of the same world. */
     "setBlock": (position: any, stateId: any) => any
+    /** Set the block action at position `position` to `actionId` and `actionParam`.,    * ,    * ``blockType`` is only required when the block at the location is a fake block.,    * This will only be caused by using ``player.sendBlock``.,    * ,    * This will not make any changes to the server's world and only sends it to the user as a local action.    */
     "sendBlockAction": (position: any, actionId: any, actionParam: any, blockType: any) => Promise<void>
+    /** Sets a block action and sends the block action to all players in the same world.,    * ,    * This will not make any changes to the server's world    */
     "setBlockAction": (position: any, actionId: any, actionParam: any) => any
   }
 }

src/lib/modules/channels.ts

@@ -20,6 +20,7 @@ export const player = (player: Player) => {
 }
 declare global {
   interface Player {
+    /** Send the specified `brand` to the player or `flying-squid` by default */
     "sendBrand": (brand?: string) => Promise<void>
   }
 }

src/lib/modules/chat.ts

@@ -169,13 +169,19 @@ export const player = function (player: Player, serv: Server) {
 }
 declare global {
   interface Server {
+    /** Broadcasts `message` to all the players with the optional `color`. */
     "broadcast": (message: any, { whitelist, blacklist, system }?: { whitelist?: any; blacklist?: any[] | undefined; system?: boolean | undefined }) => void
+    /** @internal */
     "color": { black: string; dark_blue: string; dark_green: string; dark_cyan: string; dark_red: string; purple: string; dark_purple: string; gold: string; gray: string; grey: string; dark_gray: string; dark_grey: string; blue: string; green: string; aqua: string; cyan: string; red: string; pink: string; light_purple: string; yellow: string; white: string; random: string; obfuscated: string; bold: string; strikethrough: string; underlined: string; underline: string; italic: string; italics: string; reset: string }
+    /** @internal */
     "parseClassic": (message: any) => any
   }
   interface Player {
+    /** sends `message` to the player */
     "chat": (message: any) => void
+    /** @internal */
     "emptyChat": (count?: number) => void
+    /** @internal */
     "system": (message: any) => void
   }
 }

src/lib/modules/commands.ts

@@ -364,15 +364,21 @@ export const server = function (serv: Server, { version }: Options) {
 }
 declare global {
   interface Player {
+    /** handle `command` */
     "handleCommand": (str: string) => Promise<void>
   }
   interface Entity {
+    /** @internal */
     "selectorString": (str: string) => Entity[]
   }
   interface Server {
+    /** @internal */
     "handleCommand": (str: string) => Promise<void>
+    /** @internal */
     "selector": (type: any, opt: any, selfEntityId: any) => Entity[]
+    /** Returns an array of entities that satisfies the given command selector string `str`, execution position `pos`, execution world `world`, and the ID of the entity that initiated the execution `ctxEntityId`.,    * ,    * Valid selector string values are names of online players and [valid target selector variables](https://minecraft.fandom.com/wiki/Target_selectors#Target_selector_variables).,    * ,    * Setting `allowUser` to `true` (default value) enables players to be included in the returned array, disables otherwise.    */
     "selectorString": (str: string, pos?: Vec3, world?: any, allowUser?: boolean | undefined, ctxEntityId?: any) => Entity[]
+    /** @internal */
     "posFromString": (str: string, pos: number) => any
   }
 }

src/lib/modules/communication.ts

@@ -52,20 +52,33 @@ export const entity = function (entity: Entity, serv: Server) {
 }
 declare global {
   interface Server {
+    /** @internal */
     "_writeAll": (packetName: any, packetFields: any) => any
+    /** @internal */
     "_writeArray": (packetName: any, packetFields: any, players: any) => any
+    /** @internal */
     "_writeNearby": (packetName: any, packetFields: any, loc: any) => any
+    /** Returns array of players within loc. loc is a required paramater. The object contains:,    * ,    * * world: World position is in,    * * position: Center position,    * * radius: Distance from position    */
     "getNearby": ({ world, position, radius }: { world: any; position: any; radius?: number | undefined }) => any
+    /** @internal */
     "getNearbyEntities": ({ world, position, radius }: { world: any; position: any; radius?: number | undefined }) => any[]
   }
   interface Entity {
+    /** Gets all entities nearby (within entity.viewDistance) */
     "getNearby": () => any
+    /** Gets every player other than self (all players if entity is not a player) */
     "getOtherPlayers": () => any
+    /** Get every other entity other than self */
     "getOthers": () => any
+    /** Gets all nearby players regardless of what client thinks */
     "getNearbyPlayers": (radius?: any) => any
+    /** Gets all nearby players that client can see */
     "nearbyPlayers": (radius?: any) => any
+    /** @internal */
     "_writeOthers": (packetName: any, packetFields: any) => any
+    /** @internal */
     "_writeOthersNearby": (packetName: any, packetFields: any) => any
+    /** @internal */
     "_writeNearby": (packetName: any, packetFields: any) => any
   }
 }

src/lib/modules/daycycle.ts

@@ -85,8 +85,11 @@ export const server = function (serv: Server) {
 }
 declare global {
   interface Server {
+    /** Set daylight cycle time in ticks. See `serv.time` for more info. */
     "setTime": (time: any) => void
+    /** Default `true`. If false, time will not automatically pass. */
     "doDaylightCycle": boolean
+    /** Current daylight cycle time in ticks. Morning is 0, noon is 6000, evening is 12000, and night is 18000.,    * Resets to 0 at 24000. Use `serv.setTime(time)` to set the time.    */
     "time": number
   }
 }

src/lib/modules/effects.ts

@@ -107,10 +107,15 @@ export const server = function (serv: Server, options: Options) {
 }
 declare global {
   interface Entity {
+    /** @internal */
     "effects": {}
+    /** @internal */
     "sendEffect": (effectId: any, { amplifier, duration, particles, whitelist, blacklist }?: { amplifier?: number | undefined; duration?: number | undefined; particles?: boolean | undefined; whitelist?: any; blacklist?: any[] | undefined }) => void
+    /** @internal */
     "sendRemoveEffect": (effectId: any, { whitelist, blacklist }?: { whitelist?: any; blacklist?: any[] | undefined }) => void
+    /** @internal */
     "addEffect": (effectId: any, opt?: {}) => boolean
+    /** @internal */
     removeEffect: (effectId: any, opt?: any) => void
   }
 }

src/lib/modules/entities.ts

@@ -51,11 +51,17 @@ export const entity = function (entity) {
 }
 declare global {
   interface Entity {
+    /** How much time before an entity despawns (in ms) */
     deathTime?: number
+    /** How long before an entity can be picked up (in ms) */
     pickupTime?: number
+    /** Sub-category of entity. For mobs, this is which mob (Zombie/Skeleton, etc). For objects, this is which object (Arrow/Dropped item, etc) */
     name?: string
+    /** Either "player", "mob", or "object" (currently) */
     type: string
+    /** @internal */
     "sendMetadata": (data: any) => void
+    /** @internal */
     "setAndUpdateMetadata": (data: any) => void
   }
 }

src/lib/modules/experience.ts

@@ -65,13 +65,21 @@ export const server = function (serv: Server) {
 }
 declare global {
   interface Player {
+    /** @internal */
     level: number
+    /** Total experience the player has (int). Set this using player.setXp() */
     "xp": number
+    /** Number from 0 to 1.0 representing the progress bar at the bottom of the player's screen. Set this with player.setDisplayXp() */
     "displayXp": number
+    /** Level of xp the player has. Set this with player.setXpLevel() */
     "xpLevel": number
+    /** Updates the player's xp based on player.xp, player.displayXp, and player.xpLevel */
     "sendXp": () => void
+    /** Sets and sends the player's new level */
     "setXpLevel": (level: any) => void
+    /** Sets and sends the player's new display amount. num should be from 0 to 1.0 */
     "setDisplayXp": () => void
+    /** Sets the player's XP level. Options:,    * - setLevel: Calculate and set player.level (default: true),    * - setDisplay: Calculate and set player.displayXp (default: true),    * - send: Send xp packet (default: true)    */
     "setXp": (xp: any, { setLevel, setDisplay, send }?: { setLevel?: boolean | undefined; setDisplay?: boolean | undefined; send?: boolean | undefined }) => void
   }
 }

src/lib/modules/external.ts

@@ -76,13 +76,19 @@ export const entity = function (entity: Entity, serv: Server) {
 }
 declare global {
   interface Server {
+    /** List of all plugins. Use serv.plugins[pluginName] to get a plugin's object and data. */
     "plugins": {}
+    /** @internal */
     "pluginCount": number
+    /** @internal */
     "externalPluginsLoaded": boolean
+    /** @internal */
     "addPlugin": (name: any, plugin: any, set: any) => void
   }
   interface Entity {
+    /** @internal */
     "pluginData": {}
+    /** Gets object that stores data, personalized per plugin. Returns null if plugin does not exist.,    * ,    * Shortcut for: entity.pluginData[pluginName];    */
     "getData": (pluginName: any) => any
   }
 }

src/lib/modules/header.ts

@@ -11,6 +11,7 @@ export const player = function (player: Player, serv: Server, settings: Options)
 }
 declare global {
   interface Player {
+    /** @internal */
     "playerlistUpdateText": (header: any, footer: any) => void
   }
 }

src/lib/modules/health.ts

@@ -24,12 +24,18 @@ export const player = function (player: Player, serv: Server) {
 }
 declare global {
   interface Player {
+    /** @internal */
     health: number
+    /** @internal */
     food: number
+    /** @internal */
     foodSaturation: number
 
+    /** Updates the player's health and sends the relevant packet. */
     "updateHealth": (health: number) => void
+    /** Updates the player's food and sends the relevant packet. */
     "updateFood": (food: number) => void
+    /** Updates the player's food saturation and sends the relevant packet. */
     "updateFoodSaturation": (foodSaturation: number) => void
   }
 }

src/lib/modules/inventory.ts

@@ -240,13 +240,20 @@ export const player = function (player: Player, serv: Server, { version }: Optio
 }
 declare global {
   interface Player {
+    /** @internal */
     windowType: string
+    /** @internal */
     windowPos: any
     // where it comes from?
+    /** @internal */
     setEquipment: (slot: number, item: any) => void
+    /** @internal */
     "heldItemSlot": number
+    /** @internal */
     "heldItem": any
+    /** @internal */
     "inventory": any
+    /** @internal */
     "collect": (collectEntity: any) => void
   }
 }

src/lib/modules/log.ts

@@ -119,11 +119,17 @@ export const player = function (player: Player, serv: Server) {
 }
 declare global {
   interface Server {
+    /** You can override this function so you can process the message before sending it to the console. */
     formatMessage (message: any): any
+    /** Logs a `message` */
     "log": (message: any) => void
+    /** Logs a `message` as info */
     "info": (message: any) => void
+    /** Logs a `message` as error */
     "err": (message: any) => void
+    /** Logs a `message` as warning */
     "warn": (message: any) => void
+    /** Creates the log file */
     "createLog": () => void
   }
 }

src/lib/modules/login.ts

@@ -508,17 +508,27 @@ export const player = async function (player: Player, serv: Server, settings: Op
 }
 declare global {
   interface Server {
+    /** @internal */
     "hashedSeed": number[]
   }
   interface Player {
+    /** @internal */
     profileProperties: any
+    /** @internal */
     loadedChunks: Record<string, number>
+    /** @internal */
     crouching: boolean
+    /** @internal */
     op: boolean
+    /** The username of the player */
     username: string
+    /** @internal */
     "setLoadingStatus": (text: any) => void
+    /** set player gameMode to `gameMode` */
     "setGameMode": (gameMode: any) => void
+    /** @internal */
     "waitPlayerLogin": () => Promise<unknown>
+    /** login */
     "login": () => Promise<void>
   }
 }

src/lib/modules/logout.ts

@@ -41,9 +41,11 @@ export const player = function (player: Player, serv: Server, { worldFolder }: O
 }
 declare global {
   interface Server {
+    /** @internal */
     "quit": (reason?: string) => Promise<void>
   }
   interface Player {
+    /** @internal */
     "despawnEntities": (entities: any) => void
   }
 }

src/lib/modules/moderation.ts

@@ -398,23 +398,39 @@ export const player = function (player: Player, serv: Server) {
 }
 declare global {
   interface Server {
+    /** Ban player given a uuid. If the player is online, using `player.ban()`. Bans with reason or `You are banned!`. */
     "ban": (uuid: any, reason?: string) => Promise<boolean>
+    /** @internal */
     "banIP": (IP: any, reason?: string) => Promise<boolean>
+    /** Gets UUID from username. Since it needs to fetch from mojang servers, it is not immediate.,    * ,    * Arguments in format: `callback(uuid)`. `uuid` is null if no such username exists.    */
     "getUUIDFromUsername": (username: any) => Promise<unknown>
+    /** Bans players given a username. Mainly used if player is not online, otherwise use `player.ban()`. */
     "banUsername": (username: any, reason: any) => Promise<any>
+    /** @internal */
     "banUUID": (username: any, reason: any) => Promise<any>
+    /** Pardons a player given a username. */
     "pardonUsername": (username: any) => Promise<boolean>
+    /** @internal */
     "pardonUUID": (username: any) => Promise<any>
+    /** @internal */
     "pardonIP": (IP: any) => Promise<boolean>
+    /** Object of players that are banned, key is their uuid. Use `serv.getUUIDFromUsername()` if you only have their username.,    * ,    * Example player:,    * ```,    * {,    *     time: <time in epoch>,,    *     reason: <reason given>,    * },    * ```    */
     "bannedPlayers": {}
+    /** @internal */
     "bannedIPs": {}
   }
   interface Player {
+    /** kicks player with `reason` */
     "kick": (reason?: string) => void
+    /** @internal */
     "banUUID": (reason: any) => any
+    /** @internal */
     "banUsername": (reason: any) => any
+    /** @internal */
     "banIP": (reason: any) => any
+    /** @internal */
     "pardonUUID": () => any
+    /** @internal */
     "pardonUsername": () => any
   }
 }

src/lib/modules/particle.ts

@@ -52,6 +52,7 @@ export const server = function (serv: Server) {
 }
 declare global {
   interface Server {
+    /** Emits particle (see [id list](http://wiki.vg/Protocol#Particle)) at `position` in `world`.,    * ,    * Opt:,    * - whitelist: Array of players that can see the particle (can be a player object),    * - blacklist: Array of players who cannot see the particle,    * - radius: Radius that the particle can be seen from,    * - longDistance: I don't know what this is. I think this is pointless with our implenetation of radius, not sure though...,    * - size: vec3 of the size. (0,0,0) will be at an exact position, (10,10,10) will be very spread out (particles less dense),    * - count: Number of particles. 100,000,000+ will crash the client. Try not to go over 100,000 (sincerely, minecraft clients)    */
     "emitParticle": (particle: any, world: any, position: any, { whitelist, blacklist, radius, longDistance, size, count }?: { whitelist?: any; blacklist?: any[] | undefined; radius?: number | undefined; longDistance?: boolean | undefined; size?: any; count?: number | undefined }) => void
   }
 }

src/lib/modules/physics.ts

@@ -118,9 +118,13 @@ export const server = function (serv: Server) {
 }
 declare global {
   interface Entity {
+    /** Gravity of entity (non-players) to calculate physics. */
     gravity
+    /** Decreases velocity when touching blocks */
     friction: any
+    /** @internal */
     "calculatePhysics": (delta: any) => Promise<{ position: any; onGround: boolean }>
+    /** @internal */
     "sendVelocity": (vel: any, maxVel: any) => void
   }
 }