π End-to-end encrypted cloud for everything.
Dart 2faandroidauthye2eeencryptionend-to-end-encryptionfluttergolanggoogle-photosgoogle-photos-alternativeiosopensourcephotosprivacyprivacy-toolstypescriptzero-knowledge
Address documentation check review
Manav Rathi34beefb6bfdc
diff --git a/.github/checks/documentation-comments/check.mjs b/.github/checks/documentation-comments/check.mjsindex aa8986ec03..b62fe82dca 100644--- a/.github/checks/documentation-comments/check.mjs+++ b/.github/checks/documentation-comments/check.mjs@@ -41,8 +41,9 @@ if (!paths.length) throw new Error(`${root}: found no source files`);for (const path of paths) {const source = readFileSync(resolve(root, path), "utf8");if (isGenerated(source)) continue;- const clap = path.endsWith(".rs") ? clapRanges(source) : [];- for (const comment of documentationComments(source)) {+ const comments = documentationComments(source);+ const clap = path.endsWith(".rs") ? clapRanges(source, comments) : [];+ for (const comment of comments) {if (isToolInput(path, comment.text)) continue;if (clap.some(([start, end]) => comment.line >= start && comment.line <= end)) continue;console.error(@@ -67,13 +68,13 @@ function documentationComments(source) {if (/^\s*(?:\/\/\/|\/\/!)/.test(lines[i])) {const start = i;while (i < lines.length - 1 && /^\s*(?:\/\/\/|\/\/!)/.test(lines[i + 1])) i++;- comments.push({ line: start + 1, text: lines.slice(start, i + 1).join("\n") });+ comments.push({ line: start + 1, endLine: i + 1, text: lines.slice(start, i + 1).join("\n") });continue;}if (!/^\s*\/\*(?:\*|!)/.test(lines[i])) continue;const start = i;while (i < lines.length && !lines[i].includes("*/")) i++;- comments.push({ line: start + 1, text: lines.slice(start, i + 1).join("\n") });+ comments.push({ line: start + 1, endLine: i + 1, text: lines.slice(start, i + 1).join("\n") });}return comments;}@@ -93,9 +94,22 @@ function isToolInput(path, comment) {return true;}if ([".ts", ".tsx"].includes(extension)) return false;+ const annotations = comment+ .replace(/^\s*\/\*\*/, "")+ .replace(/\*\/\s*$/, "")+ .split("\n")+ .map((line) => line.replace(/^\s*\*?\s?/, "").trim())+ .filter(Boolean);return (- /^\s*\/\*\*\s*@param\s+\{[^\n]+\}\s+\S+\s*\*\/\s*$/.test(comment) ||- /^\s*\/\*\*\s*@(satisfies|type)\s+\{[^\n]+\}\s*\*\/\s*$/.test(comment)+ annotations.length > 0 &&+ annotations.every(+ (annotation) =>+ /^@(satisfies|type|returns?)\s+\{.+\}$/.test(annotation) ||+ /^@param\s+\{.+\}\s+\S+$/.test(annotation) ||+ /^@typedef\s+\{.+\}\s+\S+$/.test(annotation) ||+ /^@prop(?:erty)?\s+\{.+\}\s+\S+$/.test(annotation) ||+ /^@template(?:\s+\{.+\})?\s+\S+$/.test(annotation),+ ));}@@ -105,12 +119,14 @@ function isGenerated(source) {);}-function clapRanges(source) {+function clapRanges(source, comments) {const lines = source.split("\n");const ranges = [];for (let i = 0; i < lines.length; i++) {if (!/#\s*\[\s*derive\s*\(/.test(lines[i])) continue;- const start = i;+ let start = i + 1;+ const help = comments.find((comment) => comment.endLine === start - 1);+ if (help) start = help.line;let derive = lines[i];while (i < lines.length - 1 && !derive.includes(")]")) derive += `\n${lines[++i]}`;if (!/\b(?:Args|Parser|Subcommand)\b/.test(derive)) continue;@@ -126,7 +142,7 @@ function clapRanges(source) {if (depth) opened = true;depth -= (code.match(/}/g) ?? []).length;if (!opened || depth) continue;- ranges.push([start + 1, end + 1]);+ ranges.push([start, end + 1]);i = end;break;}diff --git a/.github/checks/documentation-comments/test.mjs b/.github/checks/documentation-comments/test.mjsindex cc7d089cc3..9a66999eb2 100644--- a/.github/checks/documentation-comments/test.mjs+++ b/.github/checks/documentation-comments/test.mjs@@ -36,6 +36,7 @@ let result = run(" */","const values = {};",].join("\n"),+ "web/returns.js": "/** @returns {string} API documentation. */\nfunction value() {}\n","rust/clap.rs": ["#[derive(clap::Parser)]","struct Args {",@@ -69,6 +70,7 @@ for (const path of ["web/type.ts:1","web/param.js:1","web/satisfies.js:1",+ "web/returns.js:1","rust/clap.rs:6","native/Value.swift:1",]) {@@ -80,12 +82,18 @@ assert.doesNotMatch(result.stderr, /rust\/clap\.rs:3/);result = run({"rust/local.rs": "// Non-obvious implementation reason.\npub fn value() {}\n","rust/args.rs": [+ "/// Printed in top-level command help.","#[derive(clap::Parser)]","pub struct Args {"," /// Printed in command help."," pub json: bool,","}",].join("\n"),+ "rust/block_args.rs": [+ "/** Printed in top-level command help. */",+ "#[derive(clap::Parser)]",+ "pub struct Args {}",+ ].join("\n"),"web/env.d.ts": '/// <reference types="vite/client" />\n',"web/config.js": ['/** @param {import("webpack").Compiler} compiler */',@@ -94,6 +102,19 @@ result = run({"const config = {};","/** @satisfies {Record<string, string>} */","const values = {};",+ "/** @returns {string} */",+ "function value() { return ''; }",+ "/**",+ " * @template T",+ " * @param {T} value",+ " * @returns {T}",+ " */",+ "function identity(value) { return value; }",+ "/**",+ " * @typedef {{ value: string }} Value",+ " * @property {string} name",+ " * @prop {number} count",+ " */",].join("\n"),"generated/value.dart": ["// Generated file. Do not edit.",diff --git a/rust/bindings/frb/locker/src/api/document_scanner_api.rs b/rust/bindings/frb/locker/src/api/document_scanner_api.rsindex e06b91f58d..8d1e3d393f 100644--- a/rust/bindings/frb/locker/src/api/document_scanner_api.rs+++ b/rust/bindings/frb/locker/src/api/document_scanner_api.rs@@ -39,6 +39,7 @@ pub struct RustPlaneLayout {pub struct RustReprocessOptions {// Same space as `RustScanResult.quad`: the decoded source image.pub quad: RustQuad,+ // Must be a multiple of 90.pub rotation_degrees: i32,pub color_mode: RustColorMode,pub max_pixels: Option<u32>,