Docstring updating

[alecandido]

Sometimes it happens that you need to update a docstring instead of generating a new one, since you already generated it in the past and you wrote your custom content, but now you add some argument, changed some default or any other stuffs like this.

Would be possible to make doq parsing the existing docstring and operate only on the diff?

Example: I add only one argument, but everything else it's still the same, so when I run doq I would like to have everything untouched apart from one more argument inserted in the correct place among parameters, according to the template.

MetaNote

I know that this feature request it's not minimal at all, but since it was an idea that came in my mind I thought to write it and let you decide if it is in the project scope or not.

[heavenshell]

I understand your request, but I'm sorry, no.
I don't have any plan to implement diff existing doctoring and updated signature.

Diff is too complex.
Preserve existing docstring?
Apply new one?
Merge old and new?

doq can't judge. Automerge is also too much complicated.
That's why I skip generate docstring if already exists.

[alecandido]

I know, you are right. My idea was to keep existing as much as possible, in order to preserve human-generated contents, but just to add new placeholders in the middle if they are not matching the old names.

It is not so much, and still it is complicated enough to make it unappealing. Maybe I will try in the future, and maybe not. Just in case: do you mind about pull requests?

[heavenshell]

Thx for comment!

I also wondering introduce diff into doq makes slow and maybe I can't maintain.

if I want to implement diff system, maybe I implement outside of doq.
(It's just an idea)

def foo(arg1, arg2):
    """foo.

    :param arg1:
    :param arg2
    """
    pass

doq --file=foo.py --style=json --force | some_cool_diff_program
(--force is boolean and if given, always generate docstring even if docstring exists)

You can get docstring JSON from doq and you can do whatever you want.
(I think UNIX pipeline is great invention 😉 )

So, sorry I can't accept introduce diff PR but extend doq output... let's discuss.

[alecandido]

Perfect, maybe you are right. I was interested mainly to use it inside vim-pydocstring, but if ever it will be implemented it does not hurt to keep it separate for a while, if it is really going to work it is always possible to merge it afterwards, or to make vim-pydocstring aware of it.