python / python/cpython

Clarify which "identifiers" in the C API are macros

Đang mở
#93,733 19 bình luận 1 reaction 0 người được giao Xem trên GitHub

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

docs topic-C-API
Ngôn ngữ chính
Python
Star
77.2k
Fork
36k
Merge trung bình
1 ngày 9 giờ
Pull request đã merge (30 ngày)
558

Mô tả

Documentation

The "Python/C API Reference Manual" is an excellent resource but could be even better
if C macros were marked as such.

For a programmer that writes directly in C it doesn't matter which identifiers are real C functions
and which are C macros. However, when Python is used through libpython only the
C functions are available. This is the case for languages embedding Python through ffilib.

As an example: Consider the C macro PyImport_ImportModuleEx and the C function PyImport_ImportModuleLevel. They are documented in a way that makes it impossible
to guess that one is a C macro.

PyObject *PyImport_ImportModuleEx(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)

PyObject *PyImport_ImportModuleLevel(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)

A look in "Python.c" (or friends import.h here) will reveal that PyImport_ImportModuleEx is a C macro.
But it would be a quality of life-improvement, if a simple "C Macro" were added below the
signature of C macros.

This "C macro" annotation could have the same style as the "Return value is a new reference" annotation.
(maybe with a different color).

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

Mở hướng dẫn đóng góp

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.

Hướng nghiên cứu

Bắt đầu với Python/C API Reference Manual và so sánh các mục được ghi chép của PyImport_ImportModuleEx và PyImport_ImportModuleLevel. Kiểm tra import.h để xác nhận sự khác biệt giữa các macro, sau đó xác định cách tạo ra các chú thích giá trị trả về hiện có. Hoàn thành khi các macro C được đánh dấu rõ ràng trong tài liệu API mà không gắn nhãn sai cho các hàm C.

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

Đánh giá

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

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.