Support for updating existing JSDoc comments?

[zeitchef]

Just found this plugin and enjoying using it. Something I'm testing is that existing JSDoc comments are not changed/updated when a function signature changes. Is this intentional? Or have I overseen something in the usage?

[heavenshell]

@zeitchef Thank you for comment.
Yes, intentional. Currently it's by design.
Should we provide something like override option?
(Delete current JSDoc and re-generate JSDoc automatically)

[zeitchef]

@heavenshell Thanks for your quick response. It seems much more intuitive to me that comments are updated automatically when the function signature changes. I would go so far as to say this should perhaps be default behavior, but I would be just as happy with a config option to override existing comments.

[heavenshell]

Thank you for comment!

comments are updated automatically when the function signature changes.

Yeah, I know update automatically is very useful, but it's hard to merge old and new.
For example.

/**
 * Edit this line by manually
 *
 * @param {number} arg1
 * @param {string} edit this line manually
 * @param {any} same2
 */
function foo(arg1: number, before1: string, same2: any) {
}

/**
 * foo. <-- Preserve or update?
 *
 * @param {number} arg1
 * @param {string} after1 <-- Preserve this or update?
 * @param {any} same2
 */
function foo(arg1: number, after1: string, same2: any) {
}

I think I will provide override option.
(I should update ast parser library)
I'll I add this update to my TODO list.
However I'm bit busy now(till end of Feb).
So, please stay tuned 🙏

[ryuheechul]

Yeah I think override sounds good as undo will allow people to go back if overriding is not what they wanted.

A trick (as a user) I found is that move existing comments not right above the function (say add a new line between comment and function) and run :JsDoc and mix and match with old and new.

[heavenshell]

@ryuheechul Thanks for comment.
I'm very busy in my primary job.
So, please stay tuned.

A trick (as a user) I found is that move existing comments not right above the function (say add a new line between comment and function) and run :JsDoc and mix and match with old and new.

Yeah, you can do it by your self(by manual editing or writing Vim script), but I'll add override option.

[alejandroscotti]

Hello! has this override feature been released? :-)

[heavenshell]

Sorry for late response and not yet.
I've been busy with my day job and haven't made progress 😰

[ryuheechul]

FYI, Neogen is also having the same issue and the logic to tackle the issue seems to be tricky. Perhaps AI approach like this one, https://github.com/jameshiew/nvim-magic could be an alternative in the meantime.

[heavenshell]

@ryuheechul
Thanks.
Yeah as I mentioned before, this is very difficult.

Most easiest implementation is override previous comment completely.
If user changed/added comment manually, that comment will be gone.

If user want to keep previous comment, maybe we should ask user to keep or override by each line(like interactive patching).
But this is hard...

So maybe I'll implement override previous comment completely for first release.

[ryuheechul]

@heavenshell Yeah I have the similar view as yours.
About the first release of such, (just in case) maybe overriding previous comment completely shouldn't be a default behaviour though (to prevent a surprise). If that feature is only enabled via intentionally turning it on, that would be great. What do you think?

[heavenshell]

@ryuheechul
Yeah, I don't like BCBreak.

Mabye I will introduce :JsDoc! command.
:JsDoc -> current behavior
:JsDoc! -> override previous jsdoc

[ryuheechul]

@heavenshell that seems intuitive!