Merge pull request #52 from robotboy655/patch33

More various improvements to the output

Author: luttje

__tests__/test-data/offline-sites/gmod-wiki/class-function-weapon-allowsautoswitchto.ts

@@ -12,7 +12,7 @@ export const json = {
   parent: 'Weapon',
   name: 'AllowsAutoSwitchTo',
   address: 'Weapon:AllowsAutoSwitchTo',
-  description: 'Returns whether the weapon allows to being switched to when a better ( Weapon:GetWeight ) weapon is being picked up.',
+  description: 'Returns whether the weapon allows to being switched to when a better ( [Weapon:GetWeight](https://wiki.facepunch.com/gmod/Weapon:GetWeight) ) weapon is being picked up.',
   realm: 'Shared',
   arguments: [],
   returns: [

__tests__/test-data/offline-sites/gmod-wiki/enums-use.ts

@@ -14,7 +14,7 @@ export const json = {
   type: 'enum',
   name: 'USE',
   address: 'USE',
-  description: `\nEnumerations used by ENTITY:Use.\n\nNot to be confused with Enums/_USE used by Entity:SetUseType.\n`,
+  description: `\nEnumerations used by [ENTITY:Use](https://wiki.facepunch.com/gmod/ENTITY:Use).\n\nNot to be confused with [Enums/_USE](https://wiki.facepunch.com/gmod/Enums/_USE) used by [Entity:SetUseType](https://wiki.facepunch.com/gmod/Entity:SetUseType).\n`,
   realm: 'Shared',
   items: [
     {

__tests__/test-data/offline-sites/gmod-wiki/hook-player-initial-spawn.ts

@@ -85,13 +85,15 @@ export const json = {
   description: `
 Called when the player spawns for the first time.
 
-See GM:PlayerSpawn for a hook called every player spawn.
+See [GM:PlayerSpawn](https://wiki.facepunch.com/gmod/GM:PlayerSpawn) for a hook called every player spawn.
 
-This hook is called before the player has fully loaded, when the player is still in seeing the \`Starting Lua\` screen. For example, trying to use the Entity:GetModel function will return the default model (\`models/player.mdl\`).
+**NOTE**: This hook is called before the player has fully loaded, when the player is still in seeing the \`Starting Lua\` screen. For example, trying to use the [Entity:GetModel](https://wiki.facepunch.com/gmod/Entity:GetModel) function will return the default model (\`models/player.mdl\`).
 
-You can send net messages starting from the player_activate event (see Game_Events).
 
-Due to the above note, sending net messages to the spawned player in this hook are highly unreliable, and they most likely won't be received (more information here: https://github.com/Facepunch/garrysmod-requests/issues/718).
+**NOTE**: You can send [net](https://wiki.facepunch.com/gmod/net) messages starting from the player_activate event (see [Game_Events](https://wiki.facepunch.com/gmod/Game_Events)).
+
+
+**WARNING**: Due to the above note, sending [net](https://wiki.facepunch.com/gmod/net) messages to the spawned player in this hook are highly unreliable, and they most likely won't be received (more information here: https://github.com/Facepunch/garrysmod-requests/issues/718).
 
 Workaround without networking:
 \`\`\`
@@ -148,13 +150,13 @@ GM = {}
 
 ---[SERVER] Called when the player spawns for the first time.
 ---
---- See GM:PlayerSpawn for a hook called every player spawn.
+--- See [GM:PlayerSpawn](https://wiki.facepunch.com/gmod/GM:PlayerSpawn) for a hook called every player spawn.
 ---
---- This hook is called before the player has fully loaded, when the player is still in seeing the \`Starting Lua\` screen. For example, trying to use the Entity:GetModel function will return the default model (\`models/player.mdl\`).
+--- **NOTE**: This hook is called before the player has fully loaded, when the player is still in seeing the \`Starting Lua\` screen. For example, trying to use the [Entity:GetModel](https://wiki.facepunch.com/gmod/Entity:GetModel) function will return the default model (\`models/player.mdl\`).
 ---
---- You can send net messages starting from the player_activate event (see Game_Events).
+--- **NOTE**: You can send [net](https://wiki.facepunch.com/gmod/net) messages starting from the player_activate event (see [Game_Events](https://wiki.facepunch.com/gmod/Game_Events)).
 ---
---- Due to the above note, sending net messages to the spawned player in this hook are highly unreliable, and they most likely won't be received (more information here: https://github.com/Facepunch/garrysmod-requests/issues/718).
+--- **WARNING**: Due to the above note, sending [net](https://wiki.facepunch.com/gmod/net) messages to the spawned player in this hook are highly unreliable, and they most likely won't be received (more information here: https://github.com/Facepunch/garrysmod-requests/issues/718).
 ---
 --- Workaround without networking:
 --- \`\`\`
@@ -173,7 +175,6 @@ GM = {}
 --- end)
 --- \`\`\`
 ---
----
 --- With networking:
 --- \`\`\`
 --- -- CLIENT

__tests__/test-data/offline-sites/gmod-wiki/library-function-concommand-gettable.ts

@@ -13,7 +13,7 @@ export const apiDefinition =
 `--- Missing description.
 concommand = {}
 
----[SHARED AND MENU] Returns the tables of all console command callbacks, and autocomplete functions, that were added to the game with concommand.Add.
+---[SHARED AND MENU] Returns the tables of all console command callbacks, and autocomplete functions, that were added to the game with [concommand.Add](https://wiki.facepunch.com/gmod/concommand.Add).
 ---
 ---[(View on wiki)](https://wiki.facepunch.com/gmod/concommand.GetTable)
 ---@return table # Table of command callback functions.

__tests__/test-data/offline-sites/gmod-wiki/library-function-coroutine-resume.ts

@@ -15,7 +15,7 @@ export const apiDefinition =
 `--- Missing description.
 coroutine = {}
 
----[SHARED AND MENU] Resumes the given coroutine and passes the given vararg to either the function arguments or the coroutine.yield that is inside that function and returns whatever yield is called with the next time or by the final return in the function.
+---[SHARED AND MENU] Resumes the given coroutine and passes the given vararg to either the function arguments or the [coroutine.yield](https://wiki.facepunch.com/gmod/coroutine.yield) that is inside that function and returns whatever yield is called with the next time or by the final return in the function.
 ---
 ---[(View on wiki)](https://wiki.facepunch.com/gmod/coroutine.resume)
 ---@param coroutine thread Coroutine to resume.

__tests__/test-data/offline-sites/gmod-wiki/panel-slider.ts

@@ -41,7 +41,7 @@ export const apiDefinition =
 ---
 ---
 ---     A simple slider featuring an numeric display.
---- Creates a slider atop a DFrame which prints its value as it's being dragged.
+---
 ---@deprecated Panel:SetActionFunction and Panel:PostMessage.         Use DNumSlider instead.
 ---@class Slider : Panel
 local Slider = {}\n\n`;

__tests__/test-data/offline-sites/gmod-wiki/struct-ang-pos.ts

@@ -14,7 +14,7 @@ export const json = {
   type: 'struct',
   name: 'AngPos',
   address: 'AngPos',
-  description: 'Table used by various functions, such as Entity:GetAttachment.',
+  description: 'Table used by various functions, such as [Entity:GetAttachment](https://wiki.facepunch.com/gmod/Entity:GetAttachment).',
   realm: 'Shared',
   fields: [
     {

__tests__/test-data/offline-sites/gmod-wiki/struct-custom-entity-fields.ts

@@ -50,12 +50,14 @@ export const apiDefinition =
 `---
 --- Information about custom fields **all** entities can have.
 ---
---- See also Structures/ENT
+--- See also [Structures/ENT](https://wiki.facepunch.com/gmod/Structures/ENT)
 ---
 ---@class Custom_Entity_Fields
 local Custom_Entity_Fields = {}
 
----\`Serverside\`, Sandbox and Sandbox derived only. Called by the Drive property to override the default drive type, which is \`drive_sandbox\`.
+---\`Serverside\`, Sandbox and Sandbox derived only.
+---
+--- Called by the Drive property to override the default drive type, which is \`drive_sandbox\`.
 ---@type function
 Custom_Entity_Fields.GetEntityDriveMode = nil
 
@@ -79,15 +81,23 @@ Custom_Entity_Fields.PreEntityCopy = nil
 ---@type function
 Custom_Entity_Fields.OnDuplicated = nil
 
----\`Shared\`, Sandbox or Sandbox derived only. If set to \`true\`, physgun will not be able to pick this entity up. This can also be set from map, see Sandbox Specific Mapping
+---\`Shared\`, Sandbox or Sandbox derived only.
+---
+--- If set to \`true\`, physgun will not be able to pick this entity up. This can also be set from map, see Sandbox Specific Mapping
 ---@type boolean
 Custom_Entity_Fields.PhysgunDisabled = nil
 
----\`Shared\`, Sandbox or Sandbox derived only. Called from GM:PhysgunPickup, overrides \`PhysgunDisabled\`
+---\`Shared\`, Sandbox or Sandbox derived only.
+---
+--- Called from GM:PhysgunPickup, overrides \`PhysgunDisabled\`
 ---@type function
 Custom_Entity_Fields.PhysgunPickup = nil
 
----\`Shared\`, Sandbox or Sandbox derived only. Controls which tools **and** properties can be used on this entity. Format is a list of strings where each string is the tool or property classname. This can also be set from map, see Sandbox Specific Mapping
+---\`Shared\`, Sandbox or Sandbox derived only.
+---
+--- Controls which tools **and** properties can be used on this entity. Format is a list of strings where each string is the tool or property classname.
+---
+--- This can also be set from map, see Sandbox Specific Mapping
 ---@type table
 Custom_Entity_Fields.m_tblToolsAllowed = nil
 

__tests__/utils/string.spec.ts

@@ -32,8 +32,8 @@ describe('putCommentBeforeEachLine', () => {
     ['hello\r\nworld', '--- hello\n--- world'],
     ['hello\n\nworld', '--- hello\n---\n--- world'],
     ['hello\r\n\r\nworld', '--- hello\n---\n--- world'],
-    ['hello\n\n\n\nworld', '--- hello\n---\n---\n---\n--- world'],
-    ['hello\r\n\r\n\r\n\r\nworld', '--- hello\n---\n---\n---\n--- world'],
+    ['hello\n\n\n\nworld', '--- hello\n---\n--- world'],
+    ['hello\r\n\r\n\r\n\r\nworld', '--- hello\n---\n--- world'],
   ])('should put a comment before each line', (input, expected, skipFirstLine = false) => {
     expect(putCommentBeforeEachLine(input, skipFirstLine)).toBe(expected);
   });

custom/class.ENT.lua

@@ -1,2 +1,2 @@
----@class ENT : Entity
+---@class ENT : ENTITY
 ENT = {}

custom/class.TOOL.lua

@@ -0,0 +1,11 @@
+---
+--- The **TOOL** table is used in Sandbox tool creation. You can find a list of callbacks on the  page and a list of methods on the  page. Do note that some of the fields below have no effect on server-side operations.
+---
+--- The tool information box drawn on the HUD while your tool is selected has 2 values that are set by [language.Add](https://wiki.facepunch.com/gmod/language.Add).
+--- * `tool.[tool mode].name` - The tool name (Note this is NOT the same as TOOL.Name)
+--- * `tool.[tool mode].desc` - The tool description
+---
+--- Ensure that all tool file names are entirely lowercase.  Including capital letters can lead to unintended behavior.
+---
+---@class TOOL : Tool
+TOOL = {}

src/api-writer/glua-api-writer.ts

@@ -158,7 +158,7 @@ export class GluaApiWriter {
     if (!this.writtenLibraryGlobals.has(page.name)) {
       let api = '';
 
-      api += page.description ? `${putCommentBeforeEachLine(page.description, false)}\n` : '';
+      api += page.description ? `${putCommentBeforeEachLine(page.description.trim(), false)}\n` : '';
 
       if (page.deprecated)
         api += `---@deprecated ${removeNewlines(page.deprecated)}\n`;
@@ -232,9 +232,8 @@ export class GluaApiWriter {
 
     api += `---@enum ${_enum.name}\n`;
 
-    if (isContainedInTable)
-    {
-      api += _enum.description ? `${putCommentBeforeEachLine(_enum.description, false)}\n` : '';
+    if (isContainedInTable) {
+      api += _enum.description ? `${putCommentBeforeEachLine(_enum.description.trim(), false)}\n` : '';
       api += `${_enum.name} = {\n`;
     }
 
@@ -243,7 +242,7 @@ export class GluaApiWriter {
         key = key.split('.')[1];
         api += `  ${key} = ${item.value}, ` + (item.description ? `--[[ ${item.description} ]]` : '') + '\n';
       } else {
-        api += item.description ? `${putCommentBeforeEachLine(item.description, false)}\n` : '';
+        api += item.description ? `${putCommentBeforeEachLine(item.description.trim(), false)}\n` : '';
         if (item.deprecated)
           api += `---@deprecated ${removeNewlines(item.deprecated)}\n`;
         api += `${key} = ${item.value}\n`;
@@ -278,9 +277,9 @@ export class GluaApiWriter {
       if (field.deprecated)
         api += `---@deprecated ${removeNewlines(field.deprecated)}\n`;
 
-      api += `---${removeNewlines(field.description).replace(/\s+/g, ' ')}\n`;
+      api += `---${putCommentBeforeEachLine(field.description.trim())}\n`;
 
-      const type = this.transformType(field.type)
+      const type = this.transformType(field.type, field.callback);
       api += `---@type ${type}\n`;
       api += `${struct.name}.${GluaApiWriter.safeName(field.name)} = ${field.default ? this.writeType(type, field.default) : 'nil'}\n\n`;
     }
@@ -335,15 +334,21 @@ export class GluaApiWriter {
       let cbStr = `fun(`;
 
       for (const arg of callback.arguments || []) {
-        cbStr += `${GluaApiWriter.safeName(arg.name)}: ${this.transformType(arg.type)}, `;
+        if (!arg.name) arg.name = arg.type;
+        if (arg.type === 'vararg') arg.name = '...';
+  
+        cbStr += `${GluaApiWriter.safeName(arg.name)}: ${this.transformType(arg.type)}${arg.default !== undefined ? `?` : ''}, `;
       }
       if (cbStr.endsWith(", ")) cbStr = cbStr.substring(0, cbStr.length-2);
       cbStr += ")";
 
-      if (callback.returns && callback.returns.length > 0) {
-        const ret = callback.returns[0];
-        cbStr += `: ${this.transformType(ret.type)}`;
+      for (const ret of callback.returns || []) {
+        if (!ret.name) ret.name = ret.type;
+        if (ret.type === 'vararg') ret.name = '...';
+
+        cbStr += `: ${this.transformType(ret.type)}${ret.default !== undefined ? `?` : ''}, `;
       }
+      if (cbStr.endsWith(", ")) cbStr = cbStr.substring(0, cbStr.length-2);
 
       return cbStr;
     }
@@ -366,20 +371,20 @@ export class GluaApiWriter {
         let types = this.transformType(arg.type, arg.callback);
         if (arg.altType) types += "|" + this.transformType(arg.altType);
 
-        luaDocComment += `---@param ${GluaApiWriter.safeName(arg.name)}${arg.default !== undefined ? `?` : ''} ${types} ${putCommentBeforeEachLine(arg.description!)}\n`;
+        luaDocComment += `---@param ${GluaApiWriter.safeName(arg.name)}${arg.default !== undefined ? `?` : ''} ${types} ${putCommentBeforeEachLine(arg.description!.trimEnd())}\n`;
       });
     }
 
     if (func.returns) {
       func.returns.forEach(ret => {
-        const description = removeNewlines(ret.description ?? '');
+        const description = putCommentBeforeEachLine(ret.description!.trimEnd());
 
         luaDocComment += `---@return `;
 
         if (ret.type === 'vararg')
           luaDocComment += 'any ...';
         else
-          luaDocComment += `${this.transformType(ret.type)}`;
+          luaDocComment += `${this.transformType(ret.type, ret.callback)}`;
 
         luaDocComment += ` # ${description}\n`;
       });