docs: translate Korean JSDoc to English #223
Conversation
WalkthroughThis update translates all code comments, documentation strings, and user-facing messages from Korean to English across the codebase. No functional, structural, or logic changes are introduced. All method signatures, exported entities, and code behavior remain unchanged, with only the explanatory and error message text updated for English readability and consistency. Changes
Sequence Diagram(s)No sequence diagrams are generated, as the changes are limited to comment and message translations without affecting control flow or feature logic. Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes Assessment against linked issues
Assessment against linked issues: Out-of-scope changesNo out-of-scope changes detected. All changes align with the objective of updating comments and messages for English readability. Poem
Note ⚡️ Unit Test Generation is now available in beta!Learn more here, or try it out under "Finishing Touches" below. 📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (2)
🚧 Files skipped from review as they are similar to previous changes (2)
✨ Finishing Touches
🧪 Generate unit tests
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
json-choi
requested review from
PENEKhun and
wnghdcjfe
and removed request for
PENEKhun
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (50)
script/llm/loader/index.ts (1)
24-29: Two Korean error messages remain – complete the translation pass
Lines 53 and 62 still log Korean strings, which diverges from the PR goal of fully converting user-facing text to English.- `${type} 파일을 찾을 수 없습니다. 기본 경로: ${defaultPaths[type].join(", ")}`, + `Cannot locate ${type} file. Searched default paths: ${defaultPaths[type].join(", ")}`, ... - logger.error(`${type} 파일이 존재하지 않습니다: ${resolvedPath}`) + logger.error(`${type} file does not exist: ${resolvedPath}`)lib/dsl/interface/testContext.ts (1)
22-25: Minor wording nitpick
Consider “fewer than 8 characters” instead of “less than 8 characters” to match typical English grammar for countable nouns.lib/dsl/interface/ItdocBuilderEntry.ts (1)
47-51: Doc-param names out of sync with interface fields
The JSDoc lists “name” but the actual property issummary. Update the list for accuracy.- * @param name API name (one-line description) - * @param tag API tag - * @param description API detailed description + * @param summary One-line API summary + * @param tag API tag + * @param description Detailed API descriptionlib/dsl/interface/field.ts (2)
37-41: Align@paramtype annotations with the actual parameter types
exampleis declared asT | ((value: T) => void), but the doc block still says
{object | function}which discards the generic information. Updating the JSDoc keeps IntelliSense accurate and avoids confusion for consumers of the library.- * @param example {object | function} Example value or validation function for the field + * @param example {T | (value: T) => void} Example value, or a validator that receives the value
47-49: Preserve the generic in the return typeThe implementation currently casts to
DSLField<FIELD_TYPES>, losing the specific typeTthat callers supply.
Although unchanged by this PR, the accompanying JSDoc now highlights the mismatch in the@returnsline. ReturningDSLField<T>is both type-safe and self-documenting.): DSLField<FIELD_TYPES> { - return { description, example, required } as DSLField<FIELD_TYPES> + return { description, example, required } as DSLField<T> }script/llm/parser/analyzer/branchAnalyzer.ts (1)
22-26: Minor wording tweak for clarityThe first sentence could read more naturally as “Determines the branch key for a conditional call.” Consider tightening it if you touch the doc block again; otherwise, looks good.
script/llm/parser/analyzer/variableAnalyzer.ts (1)
22-26: Add@returnsto document the function outputThe JSDoc now describes the parameters but omits the fact that the function is void (it mutates
ret). Explicitly documenting that it returns nothing avoids readers assuming a meaningful return value.lib/dsl/interface/describeAPI.ts (1)
32-33: Replace TODO with an explicit Express typeThe
appparameter is routinely anExpress.Application. Replacing theunknowntype removes a lint warning and improves editor support.- app: unknown, // TODO: Type specification for this + app: import("express").Application,lib/dsl/generator/builders/operation/interfaces.ts (2)
20-30: Polish JSDoc wording and styleUse an indefinite article and add a dash after the parameter name for consistency with standard JSDoc style.
/** - * Creates OpenAPI Operation object from test results. - * @param result Test result + * Creates an OpenAPI Operation object from test results. + * @param result - Test result * @returns OpenAPI Operation object */
37-42: Apply the same dash pattern to parameter docsFor consistency with the previous block:
- * @param result Test result + * @param result - Test resultlib/dsl/test-builders/validateResponse.ts (1)
20-25: Add a short description to the @throws tagClarifies generated documentation and keeps style uniform:
- * @throws {Error} Throws an error when validation fails. + * @throws {Error} When validation fails.script/llm/parser/collector/routeCollector.ts (1)
18-19: Translate remaining Korean fragmentIf full English localisation is desired, consider updating the inline directive comment:
-// @ts-expect-error - CommonJS/ES modules 호환성 이슈로 인한 타입 에러 무시 +// @ts-expect-error – Suppress type errors caused by CommonJS/ESM interoplib/config/readPackageJson.ts (1)
65-66: Optional: streamline log messageSlightly shorter wording keeps logs concise:
-logger.error("Error occurred while reading package.json.", error) +logger.error("Error reading package.json.", error)script/llm/parser/analyzer/responseAnalyzer.ts (4)
24-27: Consider adding an explicit@returnstagAll helper functions here return
void, but the absence of an explicit@returns {void}makes the documentation slightly incomplete and can confuse tooling that relies on JSDoc.
35-41: Minor doc completenessSame remark as above – adding
@returns {void}would finish the contract description forhandleJsonResponse.
60-66: Add return information
handleHeaderResponseis void-returning; add the tag for completeness and consistency with other docs in the codebase.
101-107:analyzeResponseCallJSDoc lacks return clauseThe function is void-returning, but an explicit
* @returns {void}helps automated doc generators.
script/llm/parser/utils/extractValue.ts (8)
24-27: Return type can be more specific
@returns {object}is vague. UsingRecord<string, any>(orunknown) better conveys intent and works with TS tooling.
55-57: Missing@returnsdescriptionAdd
* @returns {any} Extracted literal or `undefined`for completeness.
65-72: Document return value
extractObjectValuedescription lacks@returns. Consider documenting that it returns a plain object representing the literal structure.
134-140: Include return clause for array extractorAs above, add
@returns {any[]}(or more precise) to keep docs uniform.
180-186: Return tag missing
extractIdentifierValue’s header should include* @returns {any}
210-217: Great summary, but no return statement in docAdd
@returnsforextractValue; the header later already contains one, so you can safely drop the duplicated short summary line and keep the detailed block.
248-256: Spread resolver docs need return infoAdd
@returns {any|null}to clarify possible null-return.
337-344: Return value section
findVariableValuedocs list params but not the return; add
@returns {any}.script/llm/prompt/index.ts (1)
94-98:anycan be narrowed
@param {any} contentcould beRecord<string, unknown>to avoid swallowing type errors.script/llm/parser/analyzer/returnValueExtractor.ts (6)
26-30: Good translation – consider periodSentence ends without a period; add one for consistency.
50-54: Return wording“Whether null values are included” → “Returns
trueif any property (recursively) isnullorundefined.”
64-69: Tiny grammar nit“Return value structure” → “Return-value structure” or “Structure of the return value”.
118-123: Return description missingAdd
@returns {any}to complete the header.
128-132: Comment heading punctuationThe line ends with a colon but the next line starts a new sentence; consider removing the colon or continuing the sentence.
155-158: Parentheses stylePrefer “Prioritises” or “Gives priority to” instead of “Prioritizes” to match the rest of the British-English spelling used elsewhere.
lib/dsl/adapters/UserTestInterface.ts (1)
20-22: Minor wording nitpickConsider adding a definite article for smoother reading:
- * Defines common DSL interface. + * Defines the common DSL interface.Not required, but it slightly improves flow.
lib/dsl/generator/index.ts (1)
33-35: Consistent wording / tenseLine 34 uses the passive voice (“will be skipped”), while Line 38 logs in the present progressive (“will be skipped”). To keep logs succinct and mirror the doc comment, you could drop the future tense in the debug line:
- logger.debug("Test failure recorded, OAS generation will be skipped.") + logger.debug("Test failure recorded; automatic OAS generation skipped.")Pure style—feel free to ignore.
Also applies to: 38-38
lib/dsl/generator/TestResultCollector.ts (5)
20-20: Grammar tweakAdd a definite article for clarity:
-// Variable to store singleton instance +// Variable to store the singleton instance
24-24: Title case suggestion“Collector” is already in the type name; consider a shorter header such as:
- * Test result collector class + * Collects test results (singleton pattern)Optional.
30-32: Hyphen usageDash reads more naturally as an em-dash:
- * Constructor - set as private for singleton pattern + * Constructor — private for singleton pattern
38-39: Redundant wordingBoth lines mention “singleton instance.” You can omit “instance” in the description:
- * Returns the singleton instance. + * Returns the singleton.Purely optional.
50-52: Parameter wordingMinor tweak for subject–verb agreement:
- * Collects test results + * Collects a test resultlib/dsl/test-builders/AbstractTestBuilder.ts (1)
21-23: Streamline descriptionA shorter version avoids the double “builder” wording:
- * Abstract class containing common settings for builder classes under test-builders. + * Base class holding common settings for test builders.Optional; current text is clear.
lib/dsl/generator/builders/schema/generators/DSLFieldSchemaGenerator.ts (1)
21-34: English translation reads well – minor type-safety improvement outside scopeThe updated comments look correct.
While reviewing, I noticedconst extendedField = field as any(Line 71) in unchanged code. At some point it would be worth introducing a narrowing helper or a dedicated interface to remove theanycast, but that is outside the scope of this docs-only PR.Also applies to: 36-41, 52-57
lib/dsl/generator/builders/schema/SchemaFactory.ts (1)
73-94: Some Korean comments still remain – complete the translationLines 73-94 still contain Korean (
// DSL 필드 처리,// 배열 처리, etc.).
Consider translating them for full consistency:- // DSL 필드 처리 + // Handle DSL fields ... - // 배열 처리 + // Array handling ... - // 객체 처리 + // Object handling ... - // 기본 타입 처리 (문자열, 숫자, 불리언) + // Primitive types (string, number, boolean) ... - // 알 수 없는 타입인 경우 + // Fallback for unknown typeslib/dsl/generator/builders/schema/interfaces.ts (1)
22-26: Document default behaviour forincludeExamplefor consistency
createSchemaexplicitly documents its default (true), butgenerateSchemadoes not. Add the same note so consumers know what happens when the parameter is omitted.- * @param includeExample Whether to include example field in schema + * @param includeExample Whether to include example field in schema (default: true)lib/dsl/test-builders/RequestBuilder.ts (1)
28-30: Broaden accepted header typesThe config allows plain-string headers as well as
DSLField<string>, but the method type excludes plain strings.-public header(headers: Record<string, DSLField<string>>): this { +public header(headers: Record<string, DSLField<string> | string>): this {lib/dsl/test-builders/TestCaseConfig.ts (1)
30-31: Minor: clarify optional flag in JSDoc
apiOptionsis already optional by the?, so the comment could read “API documentation options (optional)”.lib/dsl/generator/builders/schema/BaseSchemaGenerator.ts (1)
21-28: Mismatch between interface and abstract class signature
SchemaGenerator.generateSchemaincludes the optionalincludeExampleparameter, but the abstract declaration here omits it. While TypeScript’s structural typing allows this, mirroring the interface would avoid confusion for implementers.-public abstract generateSchema(value: unknown): Record<string, unknown> +public abstract generateSchema( + value: unknown, + includeExample?: boolean +): Record<string, unknown>lib/dsl/generator/builders/schema/generators/StringSchemaGenerator.ts (1)
24-27: Clarifyvaluetype in JSDoc
valueis declared asunknown, and the implementation handles the non-string case by returning{ type: "string" }. Stating “String value” in the docblock might mislead readers into thinking only strings are accepted. Recommend rephrasing to something like “Value to analyse (if it is a string, additional metadata is inferred)”.lib/dsl/generator/commands.ts (1)
70-72: Preserve full error context in logsOnly the error message is logged, losing the stack trace that would aid debugging. Consider passing the entire
errorobject to the logger or appendingerror.stack.-const errorMessage = error instanceof Error ? error.message : "Unknown error occurred" -logger.error(`Failed to export OpenAPI Specification: ${errorMessage}`) +logger.error( + `Failed to export OpenAPI Specification: ${ + error instanceof Error ? error.message : "Unknown error occurred" + }`, + { error } // or simply `logger.error(error)` +)lib/dsl/generator/OpenAPIGenerator.ts (2)
168-172: Fallback summary string still contains Korean
operationObj.summaryfalls back to
${method.toUpperCase()} ${path} 요청The word
요청(“request”) should be translated for consistency with the rest of the update.- representativeResult.options?.summary || `${method.toUpperCase()} ${path} 요청` + representativeResult.options?.summary || `${method.toUpperCase()} ${path} request`
374-376: Hard-coded example keys remain in Korean
exampleKeyuses"에러 응답"/"성공 응답"(“error response” / “success response”).
Consider translating these literals to keep all user-facing text in English.- const exampleKey = - result.testSuiteDescription || (isErrorStatus ? "에러 응답" : "성공 응답") + const exampleKey = + result.testSuiteDescription || (isErrorStatus ? "Error response" : "Success response")
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (54)
lib/config/readPackageJson.ts(2 hunks)lib/dsl/adapters/TestFramework.ts(1 hunks)lib/dsl/adapters/UserTestInterface.ts(1 hunks)lib/dsl/adapters/index.ts(3 hunks)lib/dsl/generator/OpenAPIGenerator.ts(7 hunks)lib/dsl/generator/TestEventManager.ts(4 hunks)lib/dsl/generator/TestResultCollector.ts(2 hunks)lib/dsl/generator/builders/SchemaBuilder.ts(1 hunks)lib/dsl/generator/builders/operation/ParameterBuilder.ts(6 hunks)lib/dsl/generator/builders/operation/RequestBodyBuilder.ts(2 hunks)lib/dsl/generator/builders/operation/ResponseBuilder.ts(5 hunks)lib/dsl/generator/builders/operation/SecurityBuilder.ts(2 hunks)lib/dsl/generator/builders/operation/UtilityBuilder.ts(3 hunks)lib/dsl/generator/builders/operation/index.ts(2 hunks)lib/dsl/generator/builders/operation/interfaces.ts(1 hunks)lib/dsl/generator/builders/schema/BaseSchemaGenerator.ts(1 hunks)lib/dsl/generator/builders/schema/SchemaFactory.ts(2 hunks)lib/dsl/generator/builders/schema/constants.ts(1 hunks)lib/dsl/generator/builders/schema/generators/ArraySchemaGenerator.ts(1 hunks)lib/dsl/generator/builders/schema/generators/BooleanSchemaGenerator.ts(2 hunks)lib/dsl/generator/builders/schema/generators/DSLFieldSchemaGenerator.ts(2 hunks)lib/dsl/generator/builders/schema/generators/NumberSchemaGenerator.ts(1 hunks)lib/dsl/generator/builders/schema/generators/ObjectSchemaGenerator.ts(1 hunks)lib/dsl/generator/builders/schema/generators/StringSchemaGenerator.ts(1 hunks)lib/dsl/generator/builders/schema/index.ts(1 hunks)lib/dsl/generator/builders/schema/interfaces.ts(1 hunks)lib/dsl/generator/commands.ts(2 hunks)lib/dsl/generator/index.ts(1 hunks)lib/dsl/generator/types/OpenAPITypes.ts(2 hunks)lib/dsl/generator/types/TestResult.ts(2 hunks)lib/dsl/interface/ItdocBuilderEntry.ts(2 hunks)lib/dsl/interface/describeAPI.ts(1 hunks)lib/dsl/interface/field.ts(3 hunks)lib/dsl/interface/itDoc.ts(1 hunks)lib/dsl/interface/testContext.ts(1 hunks)lib/dsl/test-builders/AbstractTestBuilder.ts(1 hunks)lib/dsl/test-builders/RequestBuilder.ts(3 hunks)lib/dsl/test-builders/ResponseBuilder.ts(1 hunks)lib/dsl/test-builders/RootBuilder.ts(1 hunks)lib/dsl/test-builders/TestCaseConfig.ts(1 hunks)lib/dsl/test-builders/validateResponse.ts(3 hunks)lib/utils/pathResolver.ts(2 hunks)lib/utils/specParser.ts(2 hunks)script/llm/loader/index.ts(1 hunks)script/llm/parser/analyzer/branchAnalyzer.ts(2 hunks)script/llm/parser/analyzer/responseAnalyzer.ts(4 hunks)script/llm/parser/analyzer/returnValueExtractor.ts(5 hunks)script/llm/parser/analyzer/variableAnalyzer.ts(2 hunks)script/llm/parser/collector/routeCollector.ts(4 hunks)script/llm/parser/index.ts(1 hunks)script/llm/parser/utils/extractValue.ts(8 hunks)script/llm/parser/utils/fileParser.ts(5 hunks)script/llm/prompt/index.ts(3 hunks)script/makedocs/index.ts(2 hunks)
🔇 Additional comments (46)
lib/dsl/generator/builders/schema/constants.ts (1)
18-19: Translation looks good – no further action needed
English phrasing is clear and concise, matching the existing style used elsewhere in the file.lib/dsl/generator/types/OpenAPITypes.ts (1)
18-19: Comment translation reads well
No issues spotted; types remain untouched.lib/dsl/interface/itDoc.ts (1)
26-31: Translation looks good – no further action neededscript/llm/parser/utils/fileParser.ts (1)
23-29: Documentation looks goodThe English JSDoc is clear and accurately reflects the implementation. No further action needed.
script/llm/prompt/index.ts (4)
19-30: Docs translated correctly – LGTM
66-69: Escaped hyphen guidance is clearGood clarification about quoting hyphen-containing header keys.
110-116: Example block translated well – no issues
117-120: Consistent styleNice job keeping rule list succinct and imperative.
script/llm/parser/index.ts (1)
24-28: Docstring approvedClear, concise, and matches function behaviour.
lib/dsl/adapters/TestFramework.ts (1)
18-19: Comment translation looks goodThe English description is concise and accurate.
lib/dsl/test-builders/RootBuilder.ts (1)
21-27: Docs translation looks goodThe English JSDoc is concise and accurately conveys the intent of the class and method. No further action needed.
lib/dsl/generator/builders/operation/RequestBodyBuilder.ts (2)
25-34: Documentation update is clearThe new English comments accurately describe the responsibility of the builder and its method parameters/returns.
61-75:getContentTypeignores header-name case – make lookup case-insensitiveOpenAPI generation will silently fall back to
"application/json"when callers pass"Content-Type"(camel-case) or any other case variant. Consider normalising header keys so all expected variants are honoured.- if (request.headers && "content-type" in request.headers) { - const contentType = request.headers["content-type"] + if (request.headers) { + // Find `content-type` header in a case-insensitive manner + const entry = Object.entries(request.headers).find( + ([key]) => key.toLowerCase() === "content-type", + ) + if (entry) { + const contentType = entry[1][ suggest_essential_refactor ]
lib/dsl/generator/TestEventManager.ts (1)
24-31: Translated class-level comment reads wellThe description clearly explains the responsibilities and lifecycle hooks of
TestEventManager.lib/dsl/generator/builders/operation/SecurityBuilder.ts (1)
22-31: Security builder JSDoc is now clearEnglish translation is accurate and consistent with existing terminology.
lib/dsl/generator/builders/schema/generators/ObjectSchemaGenerator.ts (1)
22-41: Object-schema generator comments look goodThe updated comments precisely describe constructor arguments and method behaviour.
lib/dsl/generator/builders/schema/generators/ArraySchemaGenerator.ts (1)
20-30: Comments successfully translated – no further action requiredThe new JSDoc blocks are clear, concise, and correctly worded. No functional code has been touched, so nothing else to validate here.
Also applies to: 35-40
lib/dsl/generator/builders/schema/index.ts (1)
20-35: Documentation export comments look goodAll Korean phrases are now in English and accurately describe the exported symbols. No logic has changed and the file continues to re-export exactly the same items, so this segment is fine.
Also applies to: 36-60
lib/dsl/test-builders/ResponseBuilder.ts (1)
27-30: Primary class comment translated – one Korean inline comment remainsThe class-level description is now in English 👍.
However, Line 181 still contains a Korean inline comment (// 검증을 위한 예상 응답 본문을 우선으로 사용). For consistency with the PR objective, please translate this remaining comment as well.lib/dsl/generator/builders/schema/generators/BooleanSchemaGenerator.ts (1)
19-28: Boolean generator docs updated correctlyThe English JSDoc accurately reflects behaviour; no logic altered. Nothing further to do.
Also applies to: 30-42
lib/dsl/generator/builders/operation/ResponseBuilder.ts (5)
24-33: Comments-only change ‑ no issuesThe added English JSDoc is clear, accurate, and matches the underlying logic.
47-62: Comments-only change ‑ no issuesHeader-filter list comment now reads well in English.
65-65: Comments-only change ‑ no issues
75-78: Comments-only change ‑ no issues
109-112: Comments-only change ‑ no issueslib/utils/specParser.ts (2)
28-31: Comments-only change ‑ no issuesThe updated description correctly explains the front-matter parsing.
53-56: Comments-only change ‑ no issueslib/dsl/generator/builders/operation/UtilityBuilder.ts (4)
22-29: Comments-only change ‑ no issues
36-36: Comments-only change ‑ no issues
58-61: Comments-only change ‑ no issues
70-77: Comments-only change ‑ no issueslib/dsl/adapters/index.ts (4)
22-24: Comments-only change ‑ no issues
47-49: Comments-only change ‑ no issues
55-57: Comments-only change ‑ no issues
75-85: Comments-only change ‑ no issueslib/dsl/generator/builders/schema/SchemaFactory.ts (4)
27-36: Comments-only change ‑ no issues
42-42: Comments-only change ‑ no issues
54-57: Comments-only change ‑ no issues
63-67: Comments-only change ‑ no issueslib/dsl/generator/builders/schema/generators/NumberSchemaGenerator.ts (1)
24-28: No action needed – comment translation looks goodThe JSDoc correctly mirrors the method signature and behaviour.
lib/utils/pathResolver.ts (1)
21-25: LGTM – documentation matches behaviourlib/dsl/generator/builders/operation/ParameterBuilder.ts (1)
24-34: LGTM – comment translations look correctlib/dsl/generator/types/TestResult.ts (1)
20-38: Documentation accurately translatedThe field descriptions now clearly describe each property; no further action needed.
lib/dsl/generator/builders/SchemaBuilder.ts (1)
21-23: Documentation update is clear and accurateThe revised JSDoc is concise and fully translated. No functional impact observed.
script/makedocs/index.ts (1)
38-44: Nice touch: step-wise log messages translatedThe updated English log entries improve clarity of the generation pipeline. ✅
lib/dsl/generator/builders/operation/index.ts (1)
33-47: Comment translation looks goodAll public JSDoc blocks are now English and accurately describe behaviour.
There was a problem hiding this comment.
The common part repeats over and over again.
Schemas and Schemes are used interchangeably.
It should be divided into two parts and written correctly.
You also need to change the name of the file or function.
| terminology | meaning | example |
|---|---|---|
| Schema | Data Structure, Format, Design Chart | JSON Schema, DB Schema |
| Scheme | Procedures, Methods, Protocols | OAuth2 scheme, API key scheme |
In node.js, a scheme is typically used as the meaning of a capture protocol.
https://nodejs.org/api/url.html
When you look at mongodb - mongoose, you write schema for the data format.
https://mongoosejs.com/docs/guide.html
* docs: translate Korean JSDoc to English * docs: translate Korean JSDoc to English * docs: Add JSDoc type annotations and complete English translation * fix: edit logger text * chore: update test result parameter * docs: schemas -> schemes
2 participants
close #207
Summary by CodeRabbit