A script to autogenerate docstrings from code

API
1

codex-tools/auto-docstring at main · scottleibrand/codex-tools · GitHub is a tool I designed, Codex wrote, and I debugged/edited that takes a file containing python code, extracts the top-level functions, and generates summaries explaining what each function does, what arguments it requires, and what it returns, formatted as PEP 257 docstrings. Adding such docstrings programatically improves the readability of the code, without requiring any additional work (or foresight) from the programmer. With auto-docstring, such comments can quickly and easily be added to any existing Python code.

You can see the kind of output it gives (with the prompt in the repo) in this pull request against another project of mine with some suitable undocumented and tersely-documented python code: Add autogenerated docstrings summarizing each function by scottleibrand · Pull Request #1408 · openaps/oref0 · GitHub

I’d love to hear from others running it against their own code. One known limitations is that for now it only processes top-level functions. If you’d like to get it to work with classes and their functions as well, it needs (at least) to be extended slightly to be able to keep track of indentation properly.

What else could we do to improve this and make it truly useful?

2 Likes
3

Interesting observation. It looks like Codex does takes the function name into account when guessing what the purpose of the function is, and for trivial functions just “takes your word for it”. But when you give it a slightly less trivial function, it does a pretty good job of actually describing the function behavior even if you change the function name:

#autodoc: Original code:

def eat_dinner_outside(ws, date_format, headerFormat):
    ws.write_string(0,0, 'Filename', headerFormat)
    ws.write_string(0,1, 'Date', headerFormat)
    ws.write_string(0,2, 'Run', headerFormat)
    col=3
    for hours in range(24):
        for minutes in [0,30]:
            dt=datetime.datetime.strptime('%02d:%02d' % (hours,minutes) , '%H:%M')
            ws.write_datetime(0, col, dt, date_format)
            col=col+1

#autodoc: A comprehensive PEP 257 Google style doctring, including a brief one-line summary of the function.

def eat_dinner_outside(ws, date_format, headerFormat):
    """Write header row for eating dinner outside spreadsheet
    
    Writes the header row for the eating dinner outside spreadsheet.
    
    Args:
        ws (xlsxwriter.worksheet.Worksheet): Worksheet to write to
        date_format (xlsxwriter.format.Format): Date format to use
        headerFormat (xlsxwriter.format.Format): Header format to use
    
    Returns:
        None
    """

Without the obfuscated function name, you get this: https://github.com/openaps/oref0/pull/1408/files#diff-4cd06ea74ec8504beb6b493cae5f99402b987c84d8f02f6ef423423a3a7dbed7R105-R117

1 Like