Clarify which "identifiers" in the C API are macros
Chưa có ai nhận issue này.
- 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
Bắt đầu từ đâu
- Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
- 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.
- Fork repository và làm thay đổi trên một nhánh.
- 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