New option to include Python docstrings in the output JS as JSDoc

[JGreenlee]

The repo I am using Transcrypt for (e-mission-common) is a standalone library that gets distributed as both a JS package (npm) and a Python package (pip).

I'm gradually adding inline documentation in the Python source via docstrings so that when people import the library for use in Python projects they can benefit from autocompletion and inline documentation in their IDE. But when imported into JS projects, this doesn't work because Transcrypt doesn't convert docstrings to the JS equivalent (which would be JSDoc)

It's possible to use the -d option to get Transcrypt to include the docstrings in the output JS, but doesn't achieve what I want.

Example function:

def sum(a, b):
    """
    Adds two numbers and returns the result

    @param a: The first number
    @param b: The second number
    @return: The sum of the two numbers
    """
    return a + b

Output JS using -d:

export var sum = function (a, b) {
  return a + b;
} .__setdoc__ ('Adds two numbers and returns the result\n \n @param a: The first number\n @param b: The second number\n @return: The sum of the two numbers');

What I want:

/**
 * Adds two numbers and returns the result
 * 
 * @param a: The first number
 * @param b: The second number
 * @return: The sum of the two numbers
 */
export var sum = function (a, b) {
  return a + b;
}

---

I was actually able to achieve this result by adding this bit of code in compiler.py, around line 2664

docString = ast.get_docstring(node)
if docString:
    self.emit('/**\n * {}\n */\n', docString.replace('\n', '\n * ').replace('\'', '\\\''))

But before I created a PR, I wanted to first file an issue proposing this to see if it would be accepted.

[JennaSys]

It does seem to make sense to format the docstring in a way that is appropriate for the language. If it's not too messy to do that, it sounds like a good idea. I will just need to see if there are any historical ramifications with changing it from the way it is now.

[JGreenlee]

I was thinking this could be provided as a new option, separate from -d / --docat, so that the existing behavior is not disrupted. Maybe called -jd / --jsdoc

I don't think it is too messy to achieve if it's like my example above where the docstring text is taken verbatim, wrapped in /** and */, and placed above the JS function. That much is satisfactory for my use case at least.

If we wanted to actually parse through the docstring and convert Python-style doc into JS-style doc, I think that would get messy, especially because Python has around 3 different major conventions for docstrings and documentation styles.