chore: add --doc to test task and correct JSDocs (denoland#489)

deno.json

@@ -6,7 +6,7 @@
     "db:seed": "deno run --allow-read --allow-env --allow-net --unstable tools/seed_submissions.ts",
     "db:reset": "deno run --allow-read --allow-env --unstable tools/reset_kv.ts",
     "start": "deno run --unstable -A --watch=static/,routes/ dev.ts",
-    "test": "KV_PATH=:memory: deno test -A --unstable --parallel --coverage=./cov",
+    "test": "KV_PATH=:memory: deno test -A --unstable --parallel --coverage=./cov --doc",
     "check:license": "deno run --allow-read --allow-write tools/check_license.ts",
     "check:types": "deno check **/*.ts && deno check **/*.tsx",
     "ok": "deno fmt --check && deno lint && deno task check:license --check && deno task check:types && deno task test",

plugins/protected_routes.ts

@@ -13,16 +13,6 @@ import { ensureSignedIn, type State } from "@/middleware/session.ts";
  * {@linkcode handleNotSignedInRest}, if the request is made to a REST API
  * endpoint.
  *
- * @example
- * ```ts
- * import { FreshOptions } from "$fresh/server.ts";
- * import protectedRoutes from "@/plugins/protected_routes.ts";
- *
- * const options: FreshOptions = {
- *   plugins: [protectedRoutes]
- * }
- * ```
- *
  * @see {@link https://fresh.deno.dev/docs/concepts/plugins|Plugins documentation}
  * for more information on Fresh's plugin functionality.
  */

utils/db.ts

@@ -82,18 +82,16 @@ export function newItemProps(): Pick<Item, "id" | "score" | "createdAt"> {
 /**
  * Creates a new item in KV. Throws if the item already exists in one of the indexes.
  *
- * @example New item creation
+ * @example
  * ```ts
  * import { newItemProps, createItem } from "@/utils/db.ts";
  *
- * const item: Item = {
- *   userLogin: "example-user-login",
+ * await createItem({
+ *   userLogin: "john_doe",
  *   title: "example-title",
- *   url: "https://example.com"
- *   ..newItemProps(),
- * };
- *
- * await createItem(item);
+ *   url: "https://example.com",
+ *   ...newItemProps(),
+ * });
  * ```
  */
 export async function createItem(item: Item) {
@@ -165,19 +163,17 @@ export function newNotificationProps(): Pick<Item, "id" | "createdAt"> {
 /**
  * Creates a new notification in KV. Throws if the item already exists in one of the indexes.
  *
- * @example New notification creation
+ * @example
  * ```ts
  * import { newNotificationProps, createNotification } from "@/utils/db.ts";
  *
- * const notification: Notification = {
- *   userLogin: "example-user-login",
+ * await createNotification({
+ *   userLogin: "john_doe",
  *   type: "example-type",
  *   text: "Hello, world!",
- *   originUrl: "https://hunt.deno.land"
+ *   originUrl: "https://hunt.deno.land",
  *   ...newNotificationProps(),
- * };
- *
- * await createNotification(notification);
+ * });
  * ```
  */
 export async function createNotification(notification: Notification) {
@@ -424,14 +420,13 @@ export function newUserProps(): Pick<User, "isSubscribed"> {
  *
  * @example
  * ```ts
- * import { createUser, newUser } from "@/utils/db.ts";
+ * import { createUser, newUserProps } from "@/utils/db.ts";
  *
- * const user = {
- *   login: "login",
- *   sessionId: "sessionId",
+ * await createUser({
+ *   login: "john-doe",
+ *   sessionId: crypto.randomUUID(),
  *   ...newUserProps(),
- * };
- * await createUser(user);
+ * });
  * ```
  */
 export async function createUser(user: User) {

utils/display.ts

@@ -23,7 +23,7 @@ export function pluralize(amount: number, unit: string) {
  * @example
  * ```ts
  * import { timeAgo } from "@/utils/display.ts";
- * import { SECOND, MINUTE, HOUR } from ""std/datetime/constants.ts""
+ * import { SECOND, MINUTE, HOUR } from "std/datetime/constants.ts";
  *
  * timeAgo(new Date()); // Returns "just now"
  * timeAgo(new Date(Date.now() - MINUTE)); // Returns "2 minutes ago"