Light documentation cleanup

TTTaevas · Mar 4, 2024 · a3a3e24 · a3a3e24
1 parent cdbb4fb
commit a3a3e24
Show file tree

Hide file tree

Showing 10 changed files with 288 additions and 325 deletions.
diff --git a/lib/changelog.ts b/lib/changelog.ts
@@ -3,13 +3,9 @@ export namespace Changelog {
 		created_at: Date
 		display_version: string
 		id: number
-		/**
-		 * How many users are playing on this version of the game? (if lazer/web, should be 0, lazer doesn't show such stats)
-		 */
+		/** How many users are playing on this version of the game? (if lazer/web, should be 0, lazer doesn't show such stats) */
 		users: number
-		/**
-		 * The name of the version
-		 */
+		/** The name of the version */
 		version: string | null
 		/**
 		 * If a video is showcased on the changelog
@@ -19,9 +15,7 @@ export namespace Changelog {
 	}
 
 	export namespace Build {
-		/**
-		 * Expected from ChangelogBuildWithChangelogentriesVersions
-		 */
+		/** @obtainableFrom {@link Changelog.Build.WithChangelogentriesVersions} */
 		export interface WithUpdatestreams extends Build {
 			update_stream: UpdateStream
 		}
@@ -37,13 +31,9 @@ export namespace Changelog {
 				category: string
 				title: string | null
 				major: boolean
-				/**
-				 * Can be January 1st 1970!
-				 */
+				/** @remarks Can be January 1st 1970! */
 				created_at: Date
-				/**
-				 * Doesn't exist if no github user is associated with who's credited with the change
-				 */
+				/** @remarks Doesn't exist if no github user is associated with who's credited with the change */
 				github_user?: {
 					display_name: string
 					github_url: string | null
@@ -54,27 +44,25 @@ export namespace Changelog {
 					user_url: string | null
 				}
 				/**
-				 * Entry message in Markdown format, embedded HTML is allowed, exists only if Markdown was requested
+				 * Entry message in Markdown format, embedded HTML is allowed
+				 * @remarks Exists only if Markdown was requested
 				 */
 				message?: string | null
 				/**
-				 * Entry message in HTML format, exists only if HTML was requested
+				 * Entry message in HTML format
+				 * @remarks Exists only if HTML was requested
 				 */
 				message_html?: string | null
 
 			}[]
 		}
 
-		/**
-		 * Expected from api.getChangelogBuilds()
-		 */
+		/** @obtainableFrom {@link API.getChangelogBuilds} */
 		export interface WithUpdatestreamsChangelogentries extends WithUpdatestreams, WithChangelogentries {
 
 		}
 
-		/**
-		 * Expected from api.getChangelogBuild()
-		 */
+		/** @obtainableFrom {@link API.getChangelogBuild} */
 		export interface WithChangelogentriesVersions extends WithChangelogentries {
 			versions: {
 				next: WithUpdatestreams | null
@@ -83,9 +71,7 @@ export namespace Changelog {
 		}
 	}
 
-	/**
-	 * Expected from ChangelogBuildWithUpdatestreams
-	 */
+	/** @obtainableFrom {@link Changelog.Build.WithUpdatestreams} */
 	export interface UpdateStream {
 		id: number
 		name: string
@@ -94,13 +80,12 @@ export namespace Changelog {
 	}
 
 	export namespace UpdateStream {
-		/**
-		 * Expected from api.getChangelogStreams()
-		 */
+		/** @obtainableFrom {@link API.getChangelogStreams} */
 		export interface WithLatestbuildUsercount extends UpdateStream {
 			latest_build: Build | null
 			/**
-			 * How many users are playing on this? (if lazer/web, should be 0, lazer doesn't show such stats)
+			 * How many users are playing on this?
+			 * @remarks Should be 0 if web
 			 */
 			user_count: number
 		}

diff --git a/lib/event.ts b/lib/event.ts
@@ -9,32 +9,22 @@ export namespace Event {
 	export interface User extends Event {
 		user: {
 			username: string
-			/**
-			 * What goes after the website's URL, so for example, it could be the `/u/7276846` of `https://osu.ppy.sh/u/7276846` (or `users` instead of `u`)
-			 */
+			/** What goes after the website's URL, so for example, it could be the `/u/7276846` of `https://osu.ppy.sh/u/7276846` (or `users` instead of `u`) */
 			url: string
 		}
 	}
 
 	export interface Beatmap extends Event {
-		/**
-		 * {artist} - {title} [{difficulty_name}]
-		 */
+		/** {artist} - {title} [{difficulty_name}] */
 		title: string
-		/**
-		 * What goes after the website's URL, like it could be the `/b/2980857?m=0` of `https://osu.ppy.sh/b/2980857?m=0` (/{beatmap_id}?m={ruleset_id})
-		 */
+		/** What goes after the website's URL, like it could be the `/b/2980857?m=0` of `https://osu.ppy.sh/b/2980857?m=0` (/{beatmap_id}?m={ruleset_id}) */
 		url: string
 	}
 
 	export interface Beatmapset extends Event {
-		/**
-		 * {artist} - {title}
-		 */
+		/** {artist} - {title} */
 		title: string
-		/**
-		 * What goes after the website's URL, like it could be the `/s/689155` of `https://osu.ppy.sh/s/689155` (/{beatmapset_id})
-		 */
+		/** What goes after the website's URL, like it could be the `/s/689155` of `https://osu.ppy.sh/s/689155` (/{beatmapset_id}) */
 		url: string
 	}
 
@@ -49,13 +39,9 @@ export namespace Event {
 			ordering: number
 			slug: string
 			description: string
-			/**
-			 * If the achievement is for a specific mode only (such as pass a 2* beatmap in taiko)
-			 */
+			/** If the achievement is for a specific mode only (such as pass a 2* beatmap in taiko) */
 			mode: string | null
-			/**
-			 * May contain HTML (like have the text between <i></i>)
-			 */
+			/** @remarks May contain HTML (like have the text between <i></i>) */
 			instructions: string
 		}
 	}
@@ -88,13 +74,9 @@ export namespace Event {
 
 	export interface Rank extends User, Beatmap {
 		type: "rank"
-		/**
-		 * The grade, like "S"
-		 */
+		/** The grade, like "S" */
 		scoreRank: string
-		/**
-		 * The position achieved, like 14
-		 */
+		/** The position achieved, like 14 */
 		rank: number
 		mode: Rulesets
 	}
@@ -120,9 +102,7 @@ export namespace Event {
 		type: "usernameChange"
 		user: {
 			username: string
-			/**
-			 * What goes after the website's URL, so for example, it could be the `/u/7276846` of `https://osu.ppy.sh/u/7276846`
-			 */
+			/** What goes after the website's URL, so for example, it could be the `/u/7276846` of `https://osu.ppy.sh/u/7276846` */
 			url: string
 			previousUsername: string
 		}

diff --git a/lib/forum.ts b/lib/forum.ts
@@ -1,6 +1,10 @@
 export namespace Forum {
 	/**
-	 * Expected from api.replyForumTopic(), api.createForumTopic(), api.getForumTopicAndPosts(), api.editForumPost()
+	 * @obtainableFrom
+	 * {@link API.replyForumTopic} /
+	 * {@link API.createForumTopic} /
+	 * {@link API.getForumTopicAndPosts} /
+	 * {@link API.editForumPost}
 	 */
 	export interface Post {
 		created_at: Date
@@ -14,13 +18,16 @@ export namespace Forum {
 		body: {
 			/** Post content in HTML format */
 			html: string
-			/**  Post content in BBCode format */
+			/** Post content in BBCode format */
 			raw: string
 		}
 	}
 
 	/**
-	 * Expected from api.createForumTopic(), api.getForumTopicAndPosts(), api.editForumTopicTitle()
+	 * @obtainableFrom
+	 * {@link API.createForumTopic} /
+	 * {@link API.getForumTopicAndPosts} /
+	 * {@link API.editForumTopicTitle}
 	 */
 	export interface Topic {
 		created_at: Date
@@ -37,7 +44,7 @@ export namespace Forum {
 		user_id: number
 		poll: {
 			allow_vote_change: boolean
-			/** Can be in the future */
+			/** @remarks Can be in the future */
 			ended_at: Date | null
 			hide_incomplete_results: boolean
 			last_vote_at: Date | null
@@ -48,7 +55,7 @@ export namespace Forum {
 					bbcode: string
 					html: string
 				}
-				/** Not present if the poll is incomplete and results are hidden */
+				/** @remarks Not present if the poll is incomplete and results are hidden */
 				vote_count?: number
 			}[]
 			started_at: Date
@@ -61,7 +68,7 @@ export namespace Forum {
 	}
 }
 
-/** Feel free to use this interface to help you create polls with `api.createForumTopic()`! */
+/** Feel free to use this interface to help you create polls with {@link API.createForumTopic}! */
 export interface PollConfig {
 	title: string
 	/** The things the users can vote for */

diff --git a/lib/home.ts b/lib/home.ts
@@ -7,17 +7,13 @@ interface SearchResult {
 }
 
 export namespace SearchResult {
-	/**
-	 * Expected from api.searchUser()
-	 */
+	/** @obtainableFrom {@link API.searchUser} */
 	export interface User extends SearchResult {
 		/** The Users that have been found */
 		data: UserInterface[]
 	}
 
-	/**
-	 * Expected from api.searchWiki()
-	 */
+	/** @obtainableFrom {@link API.searchWiki} */
 	export interface Wiki extends SearchResult {
 		/** The WikiPages that have been found */
 		data: WikiPage[]