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

Open
#878 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
35/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Stale
Tech stack
javascript, python
Domain
compilers

Research direction

Start in compiler.py around line 2664 and inspect how the existing -d option handles docstrings. Determine how a separate option should emit Python docstrings as JSDoc, then verify the generated output against the example shown in the issue and add appropriate coverage if the repository provides a compiler test entry point.

Written by the indexing model from the issue text.

Description

STATE: under consideration

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.

Dominant language
Python
Stars
2.9k
Forks
218
No merged PRs in 30d

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from TranscryptOrg/Transcrypt

All issues in TranscryptOrg/Transcrypt

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.