chore: docs lint plugin

_tools/docs_lint_plugin.ts

@@ -0,0 +1,32 @@
+// Copyright 2018-2025 the Deno authors. MIT license.
+// @ts-nocheck Deno.lint namespace does not pass type checking in Deno 1.x
+
+function isInternalFile(filename: string): boolean {
+  return filename.split(/[\\/]+/).some((part) => part.startsWith("_"));
+}
+
+export default {
+  name: "deno-std-docs",
+  rules: {
+    "exported-symbol-documented": {
+      create(context) {
+        return {
+          ExportNamedDeclaration(node) {
+            if (isInternalFile(context.filename)) return;
+            const comments = context.sourceCode.getCommentsBefore(node);
+            const hasDocComment = comments.some((comment) =>
+              comment.type === "Block" && comment.value.startsWith("*")
+            );
+            if (!hasDocComment) {
+              context.report({
+                node,
+                message: "Exported symbol is missing a documentation comment.",
+                hint: "Add a documentation comment above the symbol.",
+              });
+            }
+          },
+        };
+      },
+    },
+  },
+} satisfies Deno.lint.Plugin;

_tools/docs_lint_plugin_test.ts

@@ -0,0 +1,50 @@
+// Copyright 2018-2025 the Deno authors. MIT license.
+// @ts-nocheck Deno.lint namespace does not pass type checking in Deno 1.x
+
+import docsLintPlugin from "./docs_lint_plugin.ts";
+import { assertEquals } from "@std/assert/equals";
+
+Deno.test("deno-std-docs/exported-symbol-documented", {
+  ignore: !Deno.version.deno.startsWith("2"),
+}, () => {
+  // Good
+  const diagnostics1 = Deno.lint.runPlugin(
+    docsLintPlugin,
+    "module.ts",
+    `/** This is a documented symbol */
+    export function documented() {} `,
+  );
+  assertEquals(diagnostics1, []);
+
+  // Good (internal file)
+  const diagnostics2 = Deno.lint.runPlugin(
+    docsLintPlugin,
+    "_module.ts",
+    `export function undocumented() {}`,
+  );
+  assertEquals(diagnostics2, []);
+
+  // Good (file within internal folder)
+  const diagnostics3 = Deno.lint.runPlugin(
+    docsLintPlugin,
+    "_internal/module.ts",
+    `export function undocumented() {}`,
+  );
+  assertEquals(diagnostics3, []);
+
+  // Bad
+  const diagnostics4 = Deno.lint.runPlugin(
+    docsLintPlugin,
+    "module.ts",
+    `export function undocumented() {}`,
+  );
+  assertEquals(diagnostics4, [
+    {
+      id: "deno-std-docs/exported-symbol-documented",
+      message: "Exported symbol is missing a documentation comment.",
+      range: [0, 33],
+      fix: [],
+      hint: "Add a documentation comment above the symbol.",
+    },
+  ]);
+});

bytes/concat.ts

@@ -2,6 +2,7 @@
 // This module is browser compatible.
 
 import type { Uint8Array_ } from "./_types.ts";
+// deno-lint-ignore deno-std-docs/exported-symbol-documented
 export type { Uint8Array_ };
 
 /**

bytes/repeat.ts

@@ -2,6 +2,7 @@
 // This module is browser compatible.
 import { copy } from "./copy.ts";
 import type { Uint8Array_ } from "./_types.ts";
+// deno-lint-ignore deno-std-docs/exported-symbol-documented
 export type { Uint8Array_ };
 
 /**

cache/lru_cache.ts

@@ -2,6 +2,7 @@
 // This module is browser compatible.
 
 import type { MemoizationCache } from "./memoize.ts";
+// deno-lint-ignore deno-std-docs/exported-symbol-documented
 export type { MemoizationCache };
 
 /**

cbor/sequence_decoder_stream.ts

@@ -9,6 +9,7 @@ import { CborTextDecodedStream } from "./_text_decoded_stream.ts";
 import { CborTag } from "./tag.ts";
 import type { CborMapStreamOutput, CborStreamOutput } from "./types.ts";
 
+// deno-lint-ignore deno-std-docs/exported-symbol-documented
 export {
   CborArrayDecodedStream,
   CborByteDecodedStream,

cli/unstable_progress_bar_stream.ts

@@ -7,6 +7,7 @@ import {
 
 import type { Uint8Array_ } from "./_types.ts";
 
+// deno-lint-ignore deno-std-docs/exported-symbol-documented
 export type { Uint8Array_ };
 
 /**

csv/parse.ts

@@ -11,6 +11,7 @@ import {
 } from "./_io.ts";
 import { codePointLength } from "./_shared.ts";
 
+// deno-lint-ignore deno-std-docs/exported-symbol-documented
 export type { ParseResult, RecordWithColumn };
 
 const BYTE_ORDER_MARK = "\ufeff";

deno.json

@@ -51,7 +51,7 @@
         "no-console"
       ]
     },
-    "plugins": ["./_tools/lint_plugin.ts"]
+    "plugins": ["./_tools/lint_plugin.ts", "./_tools/docs_lint_plugin.ts"]
   },
   "workspace": [
     "./assert",

encoding/ascii85.ts

@@ -2,6 +2,7 @@
 // This module is browser compatible.
 
 import type { Uint8Array_ } from "./_types.ts";
+// deno-lint-ignore deno-std-docs/exported-symbol-documented
 export type { Uint8Array_ };
 
 /**

expect/expect.ts

@@ -64,6 +64,7 @@ import { isPromiseLike } from "./_utils.ts";
 import * as asymmetricMatchers from "./_asymmetric_matchers.ts";
 import type { SnapshotPlugin, Tester } from "./_types.ts";
 
+// deno-lint-ignore deno-std-docs/exported-symbol-documented
 export type { AnyConstructor, Async, Expected } from "./_types.ts";
 
 const matchers: Record<MatcherKey, Matcher> = {

front_matter/any.ts

@@ -7,6 +7,7 @@ import { extract as extractJson } from "./json.ts";
 import type { Extract } from "./types.ts";
 import { RECOGNIZE_REGEXP_MAP } from "./_formats.ts";
 
+// deno-lint-ignore deno-std-docs/exported-symbol-documented
 export type { Extract };
 
 /**

front_matter/json.ts

@@ -5,6 +5,7 @@ import { extractFrontMatter } from "./_shared.ts";
 import { EXTRACT_JSON_REGEXP } from "./_formats.ts";
 import type { Extract } from "./types.ts";
 
+// deno-lint-ignore deno-std-docs/exported-symbol-documented
 export type { Extract };
 
 /**

front_matter/test.ts

@@ -2,6 +2,7 @@
 
 import { EXTRACT_REGEXP_MAP, type Format } from "./_formats.ts";
 
+// deno-lint-ignore deno-std-docs/exported-symbol-documented
 export type { Format };
 
 /**

front_matter/toml.ts

@@ -6,6 +6,7 @@ import { parse } from "@std/toml/parse";
 import type { Extract } from "./types.ts";
 import { EXTRACT_TOML_REGEXP } from "./_formats.ts";
 
+// deno-lint-ignore deno-std-docs/exported-symbol-documented
 export type { Extract };
 
 /**

front_matter/unstable_yaml.ts

@@ -6,6 +6,7 @@ import { parse, type ParseOptions } from "@std/yaml/parse";
 import type { Extract } from "./types.ts";
 import { EXTRACT_YAML_REGEXP } from "./_formats.ts";
 
+// deno-lint-ignore deno-std-docs/exported-symbol-documented
 export type { Extract };
 
 /**

front_matter/yaml.ts

@@ -6,6 +6,7 @@ import { parse } from "@std/yaml/parse";
 import type { Extract } from "./types.ts";
 import { EXTRACT_YAML_REGEXP } from "./_formats.ts";
 
+// deno-lint-ignore deno-std-docs/exported-symbol-documented
 export type { Extract };
 
 /**

fs/expand_glob.ts

@@ -14,6 +14,7 @@ import {
 } from "./_create_walk_entry.ts";
 import { isWindows } from "@std/internal/os";
 
+// deno-lint-ignore deno-std-docs/exported-symbol-documented
 export type { GlobOptions, WalkEntry };
 
 /** Options for {@linkcode expandGlob} and {@linkcode expandGlobSync}. */

fs/unstable_errors.js

@@ -1,3 +1,4 @@
+// deno-lint-ignore-file deno-std-docs/exported-symbol-documented
 // Copyright 2018-2025 the Deno authors. MIT license.
 
 // @ts-self-types="./unstable_errors.d.ts"

http/unstable_file_server.ts

@@ -4,6 +4,7 @@ import {
   serveDir as stableServeDir,
   type ServeDirOptions as StableServeDirOptions,
 } from "./file_server.ts";
+// deno-lint-ignore deno-std-docs/exported-symbol-documented
 export { serveFile, type ServeFileOptions } from "./file_server.ts";
 
 /**

io/iterate_reader.ts

@@ -4,6 +4,7 @@
 import { DEFAULT_BUFFER_SIZE } from "./_constants.ts";
 import type { Reader, ReaderSync } from "./types.ts";
 
+// deno-lint-ignore deno-std-docs/exported-symbol-documented
 export type { Reader, ReaderSync };
 
 /**

jsonc/parse.ts

@@ -2,6 +2,7 @@
 // This module is browser compatible.
 
 import type { JsonValue } from "@std/json/types";
+// deno-lint-ignore deno-std-docs/exported-symbol-documented
 export type { JsonValue };
 
 /**

msgpack/encode.ts

@@ -3,6 +3,7 @@
 
 import { concat } from "@std/bytes/concat";
 import type { Uint8Array_ } from "./_types.ts";
+// deno-lint-ignore deno-std-docs/exported-symbol-documented
 export type { Uint8Array_ };
 
 /**

path/glob_to_regexp.ts

@@ -9,6 +9,7 @@ import {
   globToRegExp as windowsGlobToRegExp,
 } from "./windows/glob_to_regexp.ts";
 
+// deno-lint-ignore deno-std-docs/exported-symbol-documented
 export type { GlobOptions };
 
 /**

path/join_globs.ts

@@ -6,6 +6,7 @@ import { isWindows } from "@std/internal/os";
 import { joinGlobs as posixJoinGlobs } from "./posix/join_globs.ts";
 import { joinGlobs as windowsJoinGlobs } from "./windows/join_globs.ts";
 
+// deno-lint-ignore deno-std-docs/exported-symbol-documented
 export type { GlobOptions };
 
 /**

path/normalize_glob.ts

@@ -8,6 +8,7 @@ import {
   normalizeGlob as windowsNormalizeGlob,
 } from "./windows/normalize_glob.ts";
 
+// deno-lint-ignore deno-std-docs/exported-symbol-documented
 export type { GlobOptions };
 
 /**

path/parse.ts

@@ -6,6 +6,7 @@ import type { ParsedPath } from "./types.ts";
 import { parse as posixParse } from "./posix/parse.ts";
 import { parse as windowsParse } from "./windows/parse.ts";
 
+// deno-lint-ignore deno-std-docs/exported-symbol-documented
 export type { ParsedPath } from "./types.ts";
 
 /**

path/posix/glob_to_regexp.ts

@@ -7,6 +7,7 @@ import {
   type GlobOptions,
 } from "../_common/glob_to_reg_exp.ts";
 
+// deno-lint-ignore deno-std-docs/exported-symbol-documented
 export type { GlobOptions };
 
 const constants: GlobConstants = {

path/posix/is_glob.ts

@@ -1,4 +1,5 @@
 // Copyright 2018-2025 the Deno authors. MIT license.
 // This module is browser compatible.
 
+// deno-lint-ignore deno-std-docs/exported-symbol-documented
 export { isGlob } from "../is_glob.ts";

path/posix/join_globs.ts

@@ -6,6 +6,7 @@ import { join } from "./join.ts";
 import { SEPARATOR } from "./constants.ts";
 import { normalizeGlob } from "./normalize_glob.ts";
 
+// deno-lint-ignore deno-std-docs/exported-symbol-documented
 export type { GlobOptions };
 
 /**

path/posix/normalize_glob.ts

@@ -5,6 +5,7 @@ import type { GlobOptions } from "../_common/glob_to_reg_exp.ts";
 import { normalize } from "./normalize.ts";
 import { SEPARATOR_PATTERN } from "./constants.ts";
 
+// deno-lint-ignore deno-std-docs/exported-symbol-documented
 export type { GlobOptions };
 
 /**

path/posix/parse.ts

@@ -7,6 +7,7 @@ import { stripTrailingSeparators } from "../_common/strip_trailing_separators.ts
 import { assertPath } from "../_common/assert_path.ts";
 import { isPosixPathSeparator } from "./_util.ts";
 
+// deno-lint-ignore deno-std-docs/exported-symbol-documented
 export type { ParsedPath } from "../types.ts";
 
 /**

path/windows/is_glob.ts

@@ -1,4 +1,5 @@
 // Copyright 2018-2025 the Deno authors. MIT license.
 // This module is browser compatible.
 
+// deno-lint-ignore deno-std-docs/exported-symbol-documented
 export { isGlob } from "../is_glob.ts";

path/windows/join_globs.ts

@@ -6,6 +6,7 @@ import { join } from "./join.ts";
 import { SEPARATOR } from "./constants.ts";
 import { normalizeGlob } from "./normalize_glob.ts";
 
+// deno-lint-ignore deno-std-docs/exported-symbol-documented
 export type { GlobOptions };
 
 /**

path/windows/normalize_glob.ts

@@ -5,6 +5,7 @@ import type { GlobOptions } from "../_common/glob_to_reg_exp.ts";
 import { normalize } from "./normalize.ts";
 import { SEPARATOR_PATTERN } from "./constants.ts";
 
+// deno-lint-ignore deno-std-docs/exported-symbol-documented
 export type { GlobOptions };
 
 /**

path/windows/parse.ts

@@ -6,6 +6,7 @@ import type { ParsedPath } from "../types.ts";
 import { assertPath } from "../_common/assert_path.ts";
 import { isPathSeparator, isWindowsDeviceRoot } from "./_util.ts";
 
+// deno-lint-ignore deno-std-docs/exported-symbol-documented
 export type { ParsedPath } from "../types.ts";
 
 /**

random/between.ts

@@ -1,6 +1,7 @@
 // Copyright 2018-2025 the Deno authors. MIT license.
 // This module is browser compatible.
 import type { Prng, RandomOptions } from "./_types.ts";
+// deno-lint-ignore deno-std-docs/exported-symbol-documented
 export type { Prng, RandomOptions };
 
 /**

random/get_random_values_seeded.ts

@@ -2,6 +2,7 @@
 // This module is browser compatible.
 import { Pcg32 } from "./_pcg32.ts";
 import type { RandomValueGenerator } from "./_types.ts";
+// deno-lint-ignore deno-std-docs/exported-symbol-documented
 export type { IntegerTypedArray, RandomValueGenerator } from "./_types.ts";
 
 /**

random/integer_between.ts

@@ -2,6 +2,7 @@
 // This module is browser compatible.
 import type { Prng, RandomOptions } from "./_types.ts";
 import { randomBetween } from "./between.ts";
+// deno-lint-ignore deno-std-docs/exported-symbol-documented
 export type { Prng, RandomOptions };
 
 /**

random/sample.ts

@@ -2,6 +2,7 @@
 // This module is browser compatible.
 import type { Prng, RandomOptions } from "./_types.ts";
 import { randomIntegerBetween } from "./integer_between.ts";
+// deno-lint-ignore deno-std-docs/exported-symbol-documented
 export type { Prng, RandomOptions };
 
 /**

random/seeded.ts

@@ -2,6 +2,7 @@
 // This module is browser compatible.
 import { Pcg32 } from "./_pcg32.ts";
 import type { Prng } from "./_types.ts";
+// deno-lint-ignore deno-std-docs/exported-symbol-documented
 export type { Prng } from "./_types.ts";
 
 /**

random/shuffle.ts

@@ -2,6 +2,7 @@
 // This module is browser compatible.
 import type { Prng, RandomOptions } from "./_types.ts";
 import { randomIntegerBetween } from "./integer_between.ts";
+// deno-lint-ignore deno-std-docs/exported-symbol-documented
 export type { Prng, RandomOptions };
 
 /**