fix: JSDoc parameter parsing for deeply nested parameters #16
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
raon0211
reviewed
Jan 26, 2026
| expect(result.parameters?.[0].nested?.[2].defaultValue).toBe("true"); | ||
| }); | ||
|
|
||
| it("should parse deeply nested parameter properties (3+ levels)", () => { |
There was a problem hiding this comment.
I think we should add some test cases for edge cases like this to improve robustness. For example, what happens if the parent is declared after its children?
/**
* @param {Object} config.database.connection - Connection settings
* @param {string} config.database.connection.host - Database host
* @param {number} config.database.connection.port - Database port
* @param {string} config.database.name - Database name
* @param {Object} config.database - Database settings
* @param {Object} config - Configuration object
*/
export function configure(config: any): void {
// implementation
}
Collaborator
Author
raon0211
reviewed
Jan 26, 2026
Comment on lines
163
to
201
| private insertParamAtPath({ into, path, param }: { | ||
| into: ParameterData[]; | ||
| path: string[]; | ||
| param: ParameterData; | ||
| }): void { | ||
| const [currentSegment, ...remainingPath] = path; | ||
| if (currentSegment == null) { | ||
| return; | ||
| } | ||
|
|
||
| if (isEmpty(remainingPath)) { | ||
| into.push({ ...param, name: currentSegment, nested: [] }); | ||
|
|
||
| return; | ||
| } | ||
|
|
||
| const existingChild = into.find((n) => n.name === currentSegment); | ||
| const child = existingChild ?? this.createPlaceholderObjectParam(currentSegment); | ||
| if (existingChild == null) { | ||
| into.push(child); | ||
| } | ||
|
|
||
| const nestedParam = { ...param, name: parts.slice(1).join(".") }; | ||
| parent.nested = parent.nested || []; | ||
| parent.nested.push(nestedParam); | ||
| this.insertParamAtPath({ | ||
| into: child.nested ?? [], | ||
| path: remainingPath, | ||
| param, | ||
| }); | ||
| } | ||
|
|
||
| private createPlaceholderObjectParam(name: string): ParameterData { | ||
| return { | ||
| name, | ||
| type: "Object", | ||
| description: "", | ||
| required: true, | ||
| defaultValue: undefined, | ||
| nested: [], | ||
| }; | ||
| } |
There was a problem hiding this comment.
I'm not sure this is the optimal way to write this method — it relies heavily on imperative code with mutations rather than declarative code that returns values. Also, looking at this call in isolation, it's hard to tell what the method actually does without seeing the implementation:
// Can we understand what this method does without the surrounding context?
this.insertParamAtPath({
into: child.nested ?? [],
path: remainingPath,
param,
});I think we can rewrite this to return a value instead, making it more declarative and predictable. Let me think about this for a moment.
Collaborator
Author
Zih0
force-pushed
the
fix/js-doc-parser-nested-param
branch
from
2e25ae6 to
211a2a6
Compare
Zih0
force-pushed
the
fix/js-doc-parser-nested-param
branch
from
bd5ad90 to
438196b
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Changes
Fix JSDoc parser to correctly handle deeply nested parameter properties (3+ levels)
Example
AS-IS
TO-BE