66 lines
2.6 KiB
Markdown
66 lines
2.6 KiB
Markdown
# 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
|