ComGen

A python program to generate comments for functions in C and Python files.
If you have any suggestions or if you find any bugs, please let me know.

Installation and usage

Download the repository and just run the program like this :

python3 comgen.py <path_to_file>

You can also specify multiple files (they can be in different languages) :

python3 comgen.py <path_to_file1> <path_to_file2> ...

For more simplicity, you can add an alias in your shell configuration file :

alias comgen='python3 <path_to_comgen.py>'

You can use the -h or -H or --help or help option to display the help message.

Options

To customize the comments, you need to create a file named options.ini in which you can specify the following options :

• style_start_comment : the string to use to start a block comment in C. It can be virtually any string, but it is recommended to use /** or /*! for C.
• start_command : the string to use to start the commands in the comment. It can be virtually any string, but it is recommended to use @ or \ for C.
  NB : if you want to use the \ for starting the command, write \\ in the options.ini file, because the single backslash will be interpreted as the escape character.
• author_name : the name of the author to put in the comments.
• author_email : the email of the author to put in the comments.
• date_format : the format of the date to put in the comments. It must be a string that can be used with the strftime function of the datetime module.
• style_docstring : the style of docstring to use for Python files. It can be Google, reStructuredText, Numpy or Epytext.

Here is an example of an options.ini file :

[C]
start_command = @
style_start_comment = /**
author_name = Thomas Brasdefer
author_email = thomas@hexasec.io
date_format = %d/%m/%Y

[Python]
style_docstring = Numpy

Things to know

In general, the program will not insert doc for functions/classes that already have some. If you modify, for example, the arguments of a function that already has doc, the modifications will not be applied to the doc.
For Python, the program always inserts a field for the return values (this may change in future versions), if you don't return any values, remove these fields or indicate None.

To do

[General] : allow the update of the doc according to the modifications of the functions
add other languages : C++, Java, Prolog, etc.
add integration with Neovim, VS Code, etc.

[Python] : analyze the body of the functions for the "return", "raise" and "yield" fields
add doc for classes