docs: improve documentation (#53)

* chore: arrrrgggg

permalink: http://whatthecommit.com/e690ec4ca2c19f458e249df4358cf461

* docs: use markdown links

* chore: bump deps

* docs: add external links for djs links

* chore: bump deps

* chore: nojira: no cry

permalink: http://whatthecommit.com/784d18624270ac47133b2ab9aec2efc1

.prettierignore

@@ -0,0 +1,5 @@
+.yarn/
+coverage/
+docs/
+.yarnrc.yml
+**/CHANGELOG.md

README.md

@@ -63,4 +63,4 @@ This project follows the [all-contributors](https://github.com/all-contributors/
 
 ## Projects using TagScript
 
--   [R.O.T.I](https://discord.com/api/oauth2/authorize?client_id=903690362114158632&scope=applications.commands+bot&permissions=1543892063) by @imranbarbhuiya using TagScript for their tag module.
+-   [R.O.T.I](https://discord.com/api/oauth2/authorize?client_id=903690362114158632&scope=applications.commands+bot&permissions=1543892063) by [@imranbarbhuiya](https://github.com/imranbarbhuiya) using TagScript for their tag module.

package.json

@@ -11,7 +11,7 @@
 		"clean": "node scripts/clean.mjs",
 		"clean:full": "node scripts/clean-full.mjs",
 		"docs": "typedoc",
-		"format": "prettier --cache --write \"packages/**/{src,tests,scripts}/**/*.{mjs,ts,js}\"",
+		"format": "prettier --cache --write .",
 		"lint": "eslint packages --ext mjs,js,ts --fix --cache",
 		"update": "yarn upgrade-interactive",
 		"postinstall": "husky install .github/husky",
@@ -24,10 +24,9 @@
 		"@commitlint/config-conventional": "^17.0.3",
 		"@favware/cliff-jumper": "^1.8.6",
 		"@favware/npm-deprecate": "^1.0.5",
-		"@knodes/typedoc-plugin-monorepo-readmes": "^0.23.1",
 		"@sapphire/eslint-config": "^4.3.7",
 		"@sapphire/prettier-config": "^1.4.3",
-		"@types/node": "^18.0.6",
+		"@types/node": "^18.6.3",
 		"@typescript-eslint/eslint-plugin": "^5.31.0",
 		"@typescript-eslint/parser": "^5.31.0",
 		"c8": "^7.12.0",
@@ -42,11 +41,11 @@
 		"tsup": "^6.2.1",
 		"turbo": "^1.4.0",
 		"typedoc": "^0.23.9",
-		"typedoc-monorepo-link-types": "^0.0.4",
-		"typedoc-plugin-djs-links": "^1.2.0",
+		"typedoc-plugin-external-link": "^1.0.1",
 		"typedoc-plugin-mdn-links": "^2.0.0",
+		"typedoc-plugin-resolve-crossmodule-references": "^0.3.0",
 		"typescript": "^4.7.4",
-		"vitest": "^0.20.1"
+		"vitest": "^0.20.2"
 	},
 	"repository": {
 		"type": "git",

packages/tagscript-plugin-discord/.cliff-jumperrc.yml

@@ -1,4 +1,4 @@
 name: tagscript-plugin-discord
 monoRepo: true
 packagePath: packages/tagscript-plugin-discord
-tagTemplate: "{{full-name}}@{{new-version}}"
+tagTemplate: '{{full-name}}@{{new-version}}'

packages/tagscript-plugin-discord/package.json

@@ -61,5 +61,9 @@
 	"bugs": {
 		"url": "https://github.com/imranbarbhuiya/tagscript/issues"
 	},
-	"homepage": "https://tagscript.js.org/"
+	"homepage": "https://tagscript.js.org/",
+	"typedoc": {
+		"entryPoint": "./src/index.ts",
+		"readmeFile": "./README.md"
+	}
 }

packages/tagscript-plugin-discord/src/lib/Parsers/AllowDeny.ts

@@ -49,9 +49,10 @@ export class RequiredParser extends BaseParser implements IParser {
  *
  * @example
  * ```yaml
- *    {deny(Moderator)}
- *    {deny(#general, #chat):This tag can't be run in #general and #chat.}
- *    {deny(757425366209134764, 668713062186090506, 737961895356792882):You aren't allowed to use this tag.}
+ * {deny(Moderator)}
+ * {deny(#general, #chat):This tag can't be run in #general and #chat.}
+ * {deny(757425366209134764, 668713062186090506, 737961895356792882):You aren't allowed to use this tag.}
+ * ```
  */
 
 export class DenyParser extends BaseParser implements IParser {

packages/tagscript-plugin-discord/src/lib/Parsers/Delete.ts

@@ -3,7 +3,7 @@ import { BaseParser, type Context, type IParser } from 'tagscript';
 /**
  * Delete the triggered message.
  *
- * @note Devs need to check for this property in {@link Response.actions} and if true, delete the message.
+ * @see Devs need to check for this property in [Response.actions](https://tagscript.js.org/classes/tagscript.Response.html#actions) and if true, delete the message.
  */
 export class DeleteParser extends BaseParser implements IParser {
 	public constructor() {

packages/tagscript-plugin-discord/src/lib/Parsers/Embed.ts

@@ -36,7 +36,7 @@ import type { Awaitable, EmbedData, APIEmbed } from 'discord.js';
  * {embed(description):Follow these rules to ensure a good experience in our server!}
  * {embed(field):Rule 1|Respect everyone you speak to.|false}
  * ```
- * @note The return type depends on user's input. So it might not be `EmbedData | APIEmbed`. So use a typeguard to check.
+ * @see The return type depends on user's input. So it might not be `EmbedData | APIEmbed`. So use a typeguard to check.
  */
 export class EmbedParser extends BaseParser implements IParser {
 	public constructor() {

packages/tagscript-plugin-discord/src/lib/Parsers/Silent.ts

@@ -3,7 +3,7 @@ import { BaseParser, type Context, type IParser } from 'tagscript';
 /**
  * Silence the used command outputs.
  *
- * @note Devs need to check for this property in {@link Response.actions} and if true, don't output of the command used.
+ * @see Devs need to check for this property in [Response.actions](https://tagscript.js.org/classes/tagscript.Response.html#actions) and if true, don't output of the command used.
  */
 export class SilentParser extends BaseParser implements IParser {
 	public constructor() {

packages/tagscript-plugin-discord/src/lib/Transformer/Base.ts

@@ -9,7 +9,7 @@ export interface SafeValues<T> {
 }
 
 /**
- * Transformer for {@link https://discord.js.org/#/ Discord.js} objects.
+ * Transformer for [Discord.js](https://discord.js.org/) objects.
  */
 export abstract class BaseTransformer<T extends GuildChannel | Role | User | GuildMember | Guild | CommandInteraction> implements ITransformer {
 	protected base: T;

packages/tagscript-plugin-discord/src/lib/Transformer/Guild.ts

@@ -2,7 +2,7 @@ import type { Guild } from 'discord.js';
 import { BaseTransformer } from './Base';
 
 /**
- * Transformer for Discord {@link https://discord.js.org/#/docs/discord.js/stable/class/Guild Guild}
+ * Transformer for Discord [Guild](https://discord.js.org/#/docs/discord.js/stable/class/Guild)
  *
  * @properties
  * ```yaml

packages/tagscript-plugin-discord/src/lib/Transformer/GuildMember.ts

@@ -2,7 +2,7 @@ import type { GuildMember } from 'discord.js';
 import { BaseTransformer } from './Base';
 
 /**
- * Transformer for {@link https://discord.js.org/#/docs/discord.js/stable/class/GuildMember GuildMember}.
+ * Transformer for [GuildMember](https://discord.js.org/#/docs/discord.js/stable/class/GuildMember).
  *
  * @properties
  * ```yaml

packages/tagscript-plugin-discord/src/lib/Transformer/GuildTextBasedChannel.ts

@@ -20,6 +20,7 @@ import { BaseTransformer } from './Base';
  * createdAt: Gives channel create date.
  * createdTimestamp: Gives channel create date in ms.
  * slowmode: Gives channel slowmode.
+ * ```
  */
 export class ChannelTransformer extends BaseTransformer<GuildChannel> {
 	protected override updateSafeValues() {

packages/tagscript-plugin-discord/src/lib/Transformer/Role.ts

@@ -2,7 +2,7 @@ import type { Role } from 'discord.js';
 import { BaseTransformer } from './Base';
 
 /**
- * Transformer for Discord {@link https://discord.js.org/#/docs/discord.js/stable/class/Role Role}
+ * Transformer for Discord [Role](https://discord.js.org/#/docs/discord.js/stable/class/Role).
  *
  * @properties
  * ```yaml

packages/tagscript-plugin-discord/src/lib/Transformer/User.ts

@@ -2,7 +2,7 @@ import type { User } from 'discord.js';
 import { BaseTransformer } from './Base';
 
 /**
- * Transformer for {@link https://discord.js.org/#/docs/discord.js/stable/class/User User}
+ * Transformer for [User](https://discord.js.org/#/docs/discord.js/stable/class/User).
  *
  * @properties
  * ```yaml

packages/tagscript-plugin-discord/src/lib/Utils/CommandInteraction.ts

@@ -8,6 +8,7 @@ import {
 	User
 } from 'discord.js';
 import { IntegerTransformer, ITransformer, StringTransformer } from 'tagscript';
+
 import { ChannelTransformer, MemberTransformer, RoleTransformer, UserTransformer } from '../Transformer';
 
 export const mapOptions = (options: readonly CommandInteractionOption[], transformers: Record<string, ITransformer>, prefix = '') => {
@@ -67,7 +68,7 @@ export const mapOptions = (options: readonly CommandInteractionOption[], transfo
 
 /**
  *
- * Resolves {@link  https://discord.js.org/#/docs/discord.js/stable/class/CommandInteractionOptionResolver CommandInteractionOptionResolver} options into {@link Record<string, ITransformer>}.
+ * Resolves [CommandInteractionOptionResolver](https://discord.js.org/#/docs/discord.js/stable/class/CommandInteractionOptionResolver) options to transformers.
  *
  * @usage
  * ```typescript

packages/tagscript-plugin-discord/tests/Structures/Structures.ts

@@ -1,5 +1,11 @@
-import { ChatInputCommandInteraction, Client, Guild, GuildMember, Role, TextChannel, User } from 'discord.js';
 import {
+	ChatInputCommandInteraction,
+	Client,
+	Guild,
+	GuildMember,
+	Role,
+	TextChannel,
+	User,
 	APIUser,
 	APIRole,
 	APIGuild,
@@ -10,7 +16,7 @@ import {
 	ApplicationCommandType,
 	ApplicationCommandOptionType,
 	APIAttachment
-} from 'discord-api-types/v9';
+} from 'discord.js';
 
 export const client = new Client({ intents: [] });
 

packages/tagscript/.cliff-jumperrc.yml

@@ -1,4 +1,4 @@
 name: tagscript
 monoRepo: true
 packagePath: packages/tagscript
-tagTemplate: "{{full-name}}@{{new-version}}"
+tagTemplate: '{{full-name}}@{{new-version}}'

packages/tagscript/package.json

@@ -53,5 +53,9 @@
 	"bugs": {
 		"url": "https://github.com/imranbarbhuiya/tagscript/issues"
 	},
-	"homepage": "https://tagscript.js.org/"
+	"homepage": "https://tagscript.js.org/",
+	"typedoc": {
+		"entryPoint": "./src/index.ts",
+		"readmeFile": "./README.md"
+	}
 }

packages/tagscript/src/lib/Interpreter/Interpreter.ts

@@ -67,7 +67,7 @@ export class Interpreter {
 	 * @param tagLimit
 	 * @param parenType Whether the parameter should be followed after a "." or use parenthesis or both.
 	 * @param keyValues Additional key value pairs that may be used by parsers during parsing.
-	 * @returns {@link Response} class containing the raw string, processed body, actions and variables.
+	 * @returns {Promise<Response>} {@link Response} class containing the raw string, processed body, actions and variables.
 	 */
 	public async run(
 		message: string,

scripts/externalConfig.js

@@ -0,0 +1,61 @@
+const packageNames = ['discord.js'];
+
+/**
+ *
+ * @type {import('typedoc-plugin-external-link').getURL}
+ */
+function getURL(_, type) {
+	switch (type) {
+		case 'BaseChannel':
+		case 'Channel':
+			return 'https://discord.js.org/#/docs/discord.js/main/class/BaseChannel';
+		case 'ChatInputCommandInteraction':
+			return 'https://discord.js.org/#/docs/discord.js/main/class/ChatInputCommandInteraction';
+		case 'Client':
+			return 'https://discord.js.org/#/docs/discord.js/main/class/Client';
+		case 'CommandInteraction':
+			return 'https://discord.js.org/#/docs/discord.js/main/class/CommandInteraction';
+		case 'CommandInteractionOptionResolver':
+			return 'https://discord.js.org/#/docs/discord.js/main/class/CommandInteractionOptionResolver';
+		case 'Guild':
+			return 'https://discord.js.org/#/docs/discord.js/main/class/Guild';
+		case 'GuildMember':
+			return 'https://discord.js.org/#/docs/discord.js/main/class/GuildMember';
+		case 'Role':
+			return 'https://discord.js.org/#/docs/discord.js/main/class/Role';
+		case 'TextChannel':
+			return 'https://discord.js.org/#/docs/discord.js/main/class/TextChannel';
+		case 'User':
+			return 'https://discord.js.org/#/docs/discord.js/main/class/User';
+
+		case 'CommandInteractionOption':
+			return 'https://discord.js.org/#/docs/discord.js/main/typedef/CommandInteractionOption';
+
+		case 'ApplicationCommandOptionType':
+			return 'https://discord-api-types.dev/api/discord-api-types-v10/enum/ApplicationCommandOptionType';
+		case 'ApplicationCommandType':
+			return 'https://discord-api-types.dev/api/discord-api-types-v10/enum/ApplicationCommandType';
+		case 'InteractionType':
+			return 'https://discord-api-types.dev/api/discord-api-types-v10/enum/InteractionType';
+
+		case 'APIAttachment':
+			return 'https://discord-api-types.dev/api/discord-api-types-v10/interface/APIAttachment';
+		case 'APIEmbed':
+			return 'https://discord-api-types.dev/api/discord-api-types-v10/interface/APIEmbed';
+		case 'APIGuild':
+			return 'https://discord-api-types.dev/api/discord-api-types-v10/interface/APIGuild';
+		case 'APIGuildMember':
+			return 'https://discord-api-types.dev/api/discord-api-types-v10/interface/APIGuildMember';
+		case 'APIRole':
+			return 'https://discord-api-types.dev/api/discord-api-types-v10/interface/APIRole';
+
+		case 'APIApplicationCommandInteraction':
+			return 'https://discord-api-types.dev/api/discord-api-types-v10#APIApplicationCommandInteraction';
+		case 'APIChannel':
+			return 'https://discord-api-types.dev/api/discord-api-types-v10#APIChannel';
+	}
+
+	return undefined;
+}
+
+module.exports = { packageNames, getURL };

typedoc.json

@@ -1,17 +1,11 @@
 {
 	"$schema": "https://typedoc.org/schema.json",
 	"cleanOutputDir": true,
-	"entryPointStrategy": "resolve",
-	"entryPoints": ["packages/tagscript/src/index.ts", "packages/tagscript-plugin-discord/src/index.ts"],
+	"entryPointStrategy": "packages",
+	"entryPoints": ["packages/tagscript/", "packages/tagscript-plugin-discord/"],
 	"excludeExternals": true,
-	"hideGenerator": true,
-	"markedOptions": {
-		"gfm": true,
-		"mangle": false,
-		"smartypants": true
-	},
 	"name": "TagScript",
 	"out": "./docs/",
-	"readme": "./README.md",
-	"tsconfig": "./tsconfig.base.json"
+	"tsconfig": "./tsconfig.base.json",
+	"externalLinkPath": "scripts/externalConfig.js"
 }