Skip to content

armgit / ente

Public Imported from GitHub
0

πŸ’š End-to-end encrypted cloud for everything.

Address documentation check review

Manav Rathi34beefb6bfdc
diff --git a/.github/checks/documentation-comments/check.mjs b/.github/checks/documentation-comments/check.mjs
index 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.mjs
index 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.rs
index 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>,