Already written docstring

[hugorichard]

Thanks for this fantastic package. I will definitely use this.

However some features are missing in my opinion.

Some times I have a "return" in my function but only write it as
def f(a, b, c) and not as def f(a, b, c) -> float so it would be nice to still be able to specify the return parameter in the doc even without specifying its type in the function definition.

Another usecase is that sometimes part of the docs are already written. It would be nice to have a default mode where the already written text is kept as a default so that I can use the package to modify only the doc of one argument.

Lastly, I notice the "prompt" option nicely format the doc. It would surely be possible to re-format badly written doc (such as when everything is written on a single line instead of nicely given as a paragraph.

Do you thing some of these things are worth to implement ?

[douglasdavis]

Thanks for this fantastic package. I will definitely use this.

Great!

Some times I have a "return" in my function but only write it as
def f(a, b, c) and not as def f(a, b, c) -> float so it would be nice to still be able to specify the return parameter in the doc even without specifying its type in the function definition.

I agree this is a feature that should be supported. I'll take a look at this soon as it should be pretty simple.

Another usecase is that sometimes part of the docs are already written. It would be nice to have a default mode where the already written text is kept as a default so that I can use the package to modify only the doc of one argument.

I don't have time right now to work on this but I would welcome a PR. Off the top of my head I think one could search the existing docstring for the single argument of interest, ask the user for new text, and insert it at the location of the existing argument in the docstring. Or if the user's cursor is on an argument, modify only that argument's description. I imagine the difficulty would be properly removing an existing argument description and replacing it with a new one while maintaining proper numpydoc format and not removing a part of the docstring that is meant to be preserved.

Lastly, I notice the "prompt" option nicely format the doc. It would surely be possible to re-format badly written doc (such as when everything is written on a single line instead of nicely given as a paragraph.

This isn't exactly a target of numpydoc.el. One can easily reformat long lines in Emacs with the builtin fill-paragraph function (which has a default binding of M-q). It's used in numpydoc.el here:

numpydoc.el/numpydoc.el

Lines 337 to 345 in 2d280dd

	(defun numpydoc--fill-last-insertion ()
	"Fill paragraph on last inserted text."
	(save-excursion
	(move-beginning-of-line nil)
	(back-to-indentation)
	(set-mark-command nil)
	(move-end-of-line nil)
	(fill-paragraph nil t)
	(deactivate-mark)))

[hugorichard]

Thanks a lot for this answer. I didn't know about the fill-paragraph function. This is definitely very useful.
I'll think a bit on how to do the second thing. I would know how to do it in python but definitely not in e-lisp.
Anyway thanks for the great work !

[douglasdavis]

I've added a new option to always insert a Returns block in #11 I'll leave this open since that was only part of the issue.

[hugorichard]

Nice ! Thanks for this.