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

Đang mở
#878 2 bình luận 0 reaction 0 người được giao Xem trên GitHub

Chưa có ai nhận issue này.

Đánh giá

Độ khó
4/5
Thời gian dự kiến
3-5 ngày
Mức phù hợp với người mới
35/100
Loại issue
Tính năng
Độ rõ ràng
Khá rõ ràng
Mức độ hoạt động
Đình trệ
Công nghệ
javascript, python
Lĩnh vực
compilers

Hướng nghiên cứu

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.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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.

Ngôn ngữ chính
Python
Star
2.9k
Fork
218
Không có pull request nào được merge trong 30 ngày

Hướng dẫn đóng góp

Chưa lập chỉ mục được hướng dẫn đóng góp cho kho mã nguồn này

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của TranscryptOrg/Transcrypt

Tất cả issue của TranscryptOrg/Transcrypt

Issue tương tự

Thêm issue về Python

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.