docs(jsdoc): Add document comments to all exported codes (#46)

Developers can notice what the code means.

src/libs/content.ts

@@ -3,6 +3,33 @@ import type { StatusCode } from "@std/http";
 
 import { getRepository, githubToken } from "./env.ts";
 
+/**
+ * Get the content of the repository.
+ * @internal
+ *
+ * @param ref The name of the branch, tag or commit hash
+ * @returns The content of the repository and the status code
+ *
+ * @example Use the default branch
+ * ```ts
+ * const [content, status] = await getContent();
+ * ```
+ * @example Use a specific branch
+ * ```ts
+ * const branch = "main";
+ * const [content, status] = await getContent(branch);
+ * ```
+ * @example Use a specific tag
+ * ```ts
+ * const tag = "v1.0.0";
+ * const [content, status] = await getContent(tag);
+ * ```
+ * @example Use a specific commit
+ * ```ts
+ * const commit = "a1b2c3d4e5f6";
+ * const [content, status] = await getContent(commit);
+ * ```
+ */
 export async function getContent(
   ref: string | undefined = undefined,
 ): Promise<[string, StatusCode]> {

src/libs/env.ts

@@ -1,5 +1,15 @@
 import type { Repository } from "./types.ts";
 
+/**
+ * Get the repository details from the environment variables.
+ *
+ * @returns {Repository} The repository type
+ *
+ * @example
+ * ```ts
+ * const repository = getRepository();
+ * ```
+ */
 export function getRepository(): Repository {
   const repository: Repository = {
     owner: Deno.env.get("REPOSITORY_OWNER") ?? "",
@@ -16,4 +26,12 @@ export function getRepository(): Repository {
   return repository;
 }
 
+/**
+ * The GitHub token from the environment variables.
+ *
+ * @example
+ * ```ts
+ * const token = githubToken;
+ * ```
+ */
 export const githubToken: string | undefined = Deno.env.get("GITHUB_TOKEN");

src/libs/redirect.ts

@@ -3,6 +3,38 @@ import type { UserAgent } from "@std/http/user-agent";
 import { getRepository } from "./env.ts";
 import { getGitHubUrl } from "./utils.ts";
 
+/**
+ * Check if accessed from a browser and return the GitHub URL.
+ * @internal
+ *
+ * @param userAgent The user agent accessed from
+ * @param ref="master" The branch, tag, or commit hash
+ * @returns The GitHub repository URL or null
+ *
+ * @example Use the default branch
+ * ```ts
+ * const userAgent = new UserAgent("Chrome/1.2.3");
+ * const url: URL | null = checkRedirect(userAgent);
+ * ```
+ * @example Use a specific branch
+ * ```ts
+ * const userAgent = new UserAgent("Chrome/1.2.3");
+ * const branch = "main";
+ * const url: URL | null = checkRedirect(userAgent, branch);
+ * ```
+ * @example Use a specific tag
+ * ```ts
+ * const userAgent = new UserAgent("Chrome/1.2.3");
+ * const tag = "v1.0.0";
+ * const url: URL | null = checkRedirect(userAgent, tag);
+ * ```
+ * @example Use a specific commit
+ * ```ts
+ * const userAgent = new UserAgent("Chrome/1.2.3");
+ * const commit = "a1b2c3d4e5f6";
+ * const url: URL | null = checkRedirect(userAgent, commit);
+ * ```
+ */
 export function checkRedirect(
   userAgent: UserAgent,
   ref: string = "master",

src/libs/test_utils.ts

@@ -2,24 +2,79 @@ import { UserAgent } from "@std/http/user-agent";
 
 import type { Repository } from "./types.ts";
 
+/**
+ * Sample repository for test.
+ *
+ * @example
+ * ```ts
+ * const repository = testRepo;
+ * ```
+ */
 export const testRepo: Repository = {
   owner: "denoland",
   name: "deno",
   path: "README.md",
 };
+
+/**
+ * Sample unknown repository for test.
+ *
+ * @example
+ * ```ts
+ * const repository = unknownRepo;
+ * ```
+ */
 export const unknownRepo: Repository = {
   owner: "unknown-owner",
   name: "unknown-repo",
   path: "unknown-path",
 };
+
+/**
+ * Sample version reference for test.
+ *
+ * @example
+ * ```ts
+ * const ref = testRef;
+ * ```
+ */
 export const testRef = "v1.0.0";
+
+/**
+ * Sample user agent for test.
+ *
+ * @example
+ * ```ts
+ * const userAgent = testUserAgent;
+ * ```
+ */
 export const testUserAgent = new UserAgent("Chrome/1.2.3");
 
+/**
+ * Export the repository details to the environment variables.
+ *
+ * @param repository The repository type
+ *
+ * @example
+ * ```ts
+ * const repository = new Repository("5ouma", "reproxy", "src/server.ts");
+ * exportRepo(repository);
+ * ```
+ */
 export function exportRepo(repository: Repository) {
   Deno.env.set("REPOSITORY_OWNER", repository.owner);
   Deno.env.set("REPOSITORY_NAME", repository.name);
   Deno.env.set("REPOSITORY_PATH", repository.path);
 }
+
+/**
+ * Clear the repository details from the environment variables.
+ *
+ * @example
+ * ```ts
+ * clearRepo();
+ * ```
+ */
 export function clearRepo() {
   Deno.env.delete("REPOSITORY_OWNER");
   Deno.env.delete("REPOSITORY_NAME");

src/libs/types.ts

@@ -1,3 +1,19 @@
+/**
+ * Repository type.
+ *
+ * @property owner The repository owner
+ * @property name The repository name
+ * @property path The content path from the root of the repository
+ *
+ * @example
+ * ```ts
+ * const repository: Repository = {
+ *   owner: "5ouma",
+ *   name: "reproxy",
+ *   path: "src/server.ts",
+ * };
+ * ```
+ */
 export type Repository = {
   owner: string;
   name: string;

src/libs/utils.ts

@@ -2,6 +2,23 @@ import { join } from "@std/path";
 
 import type { Repository } from "./types.ts";
 
+/**
+ * Get the GitHub URL of the repository.
+ *
+ * @param repository The repository type
+ * @param ref="master" The reference to use
+ * @returns The GitHub repository URL
+ *
+ * @example
+ * ```ts
+ * const repository: Repository = {
+ *   owner: "5ouma",
+ *   name: "reproxy",
+ *   path: "src/server.ts",
+ * };
+ * const url: URL = getGitHubUrl(repository);
+ * ```
+ */
 export function getGitHubUrl(
   repository: Repository,
   ref: string = "master",

src/server.ts

@@ -4,6 +4,20 @@ import { UserAgent } from "@std/http/user-agent";
 
 import { checkRedirect, getContent } from "./libs/mod.ts";
 
+/**
+ * The Hono application for this project.
+ *
+ * @example Access without a user agent
+ * ```ts
+ * const res: Response = await app.request("/");
+ * ```
+ * @example Access with a user agent
+ * ```ts
+ * const res: Response = await app.request("/", {
+ *   headers: { "User-Agent": new UserAgent("Chrome/1.2.3").toString() },
+ * });
+ * ```
+ */
 export const app = new Hono();
 app
   .get("/:ref?", async (ctx: Context) => {