How to add properly parameter description?

[onekk]

Hello, I find you package useful, but I have to edit them everytime I use it.

usually the format I use and is advised as example here:

https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html#example-google

is:

Args:
    var (type):
        description

There is some way to achieve this?

Kind Regards

Carlo D.

[macurovc]

Hello, thank you for having given this package a chance. The docstring format provided by the package follows the official Google style guidelines:

https://google.github.io/styleguide/pyguide.html#383-functions-and-methods

The docstring doesn't contain the type in parentheses. The exception is for Python code that misses type annotations. Unfortunately, the package of this project doesn't support it.

[onekk]

It's a pity, as this is a convention used by many of my projects.

Kind Regards

Carlo D.

[macurovc]

I know. I originally wrote this package because I needed it at work and I always dealt with type annotated code. Nowadays I actually use this package way less often. I will see if I find some free time to extend it. Meanwhile, feel free to contribute yourself if you have the motivation. I'd be happy to get in contact and explain how the code works in case.

[onekk]

Hello, thanks for the reply.

I've managed to make these modifications:

(cl-defstruct python-insert-docstring--argument-data
  "Data associated to a function argument."
  name description atype)

(maybe would be better)

(cl-defstruct python-insert-docstring--argument-data
  "Data associated to a function argument."
  name atype description)

but I don't know very well the implication data order.

But now I can't get the way to output two lines one for the argument name and type in the form of:

   argname (atype):

and the subsequent indentend line for the description.

I've managed to get this code:

(defun (python-insert-docstring--google-docstring-argument-description (argument-data arguments-docstring-indentation)
  "Generate a docstring paragraph with the description of an argument.
Argument ARGUMENT-DATA struct with the argument data.
Argument ARGUMENTS-DOCSTRING-INDENTATION indentation of the argument paragraph."
  (let ((desc-docstring-indentation
         (concat arguments-docstring-indentation (python-insert-docstring-default-indentation))
    (name ((python-insert-docstring--argument-data-name
                argument-data))
         (description ((python-insert-docstring--argument-data-description
                        argument-data))
         (atype ((python-insert-docstring--argument-data-atype
                        argument-data))
        )
    ((python-insert-docstring--line-to-indented-paragraph (format "%s (%s):\n" name atype)
      arguments-docstring-indentation (python-insert-docstring-default-indentation)
    ((python-insert-docstring--line-to-indented-paragraph (format "%s" description)
      desc-docstring-indentation (python-insert-docstring-default-indentation)
  ))

But it is not working, I can't return (my fault I'm a beginner in elisp) the two lines.

It print only "argument description"

Obviously something is lacking.

However I have forked your repo, just in case, but I think, that there will be flag to manage the two ways, or two different functions for the two ways, maybe.

Kind Regards

Carlo D.

[macurovc]

Hi. What you propose makes sense. You can create a new top level function that can be associated with a different key-binding. You can add it next to the existing one here:

insert-docstring/python-insert-docstring.el

Line 113 in cd6419b

(defun python-insert-docstring-with-google-style-at-point ()

Extending the argument data as you proposed makes sense. You then have to populate the new field with a function similar to this one:

insert-docstring/python-insert-docstring.el

Line 182 in cd6419b

(defun python-insert-docstring--make-argument-data (argument-name)

I think that the new field must always be specified by the user, because the new docstring format is applicable only to code that misses type annotations. The python-insert-docstring--google-docstring-argument-description function can then be extended to change behavior if the new argument type field is defined:

insert-docstring/python-insert-docstring.el

Line 289 in cd6419b

(defun python-insert-docstring--google-docstring-argument-description (argument-data arguments-docstring-indentation)

You don't have to add a line break between the argument name and its description, because it's optional according to the Google Style Guide. If you want to add the line break, it's a bit more complicated, because the docstring is stored in memory as a list of lines, before being dumped to the buffer. This way it's easier to split the content of the docstring from its final formatting (this package takes care of breaking the lines that are too long).

Something that I recommend you to do is to add a unit test here:

https://github.com/macurovc/insert-docstring/blob/cd6419b74c99c06d5c48c1b289572acce1fd193b/python-insert-docstring-tests.el

I personally find it quicker to iterate on the code that I develop by running the unit test rather than always manually calling the function on some file.

The last step is extending the README.md and the top level commentary to mention the new feature, so that users are aware of it.

Feel free to open a pull request when you are ready and I'll review it. Thank you very much for your effort!

[onekk]

Many thanks, I will see your remarks after Christmas.

Probably I will need some help again, I will get in touch here, prior to making the PR.

Merry Christmas!

Kind Regards

Carlo D.

[macurovc]

No problem. Merry Christmas!