Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

Proposal: Comment Attribution Rules for Symbol Declarations

Đang mở
  • Có gì không ổn?
#1,056 6 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

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

Đánh giá

Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức phù hợp với người mới
15/100
Loại issue
Tính năng
Độ rõ ràng
Khá rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
c, cpp, go
Lĩnh vực
documentation, tooling

Hướng nghiên cứu

This is a design proposal, and the payload names no source files, tests, or entry points. Start by reading the six comments to see which rules (blank-line break, leading/inline/trailing priority, macro handling) are contested or already decided. Done means the maintainers have accepted or amended the rules, not that a patch exists; a newcomer should ask on the thread before doing anything else.

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

Mô tả

Architecture-Design feature proposal

Summary

This proposal defines how llcppg decides which comment belongs to a C/C++ symbol declaration (type, func, var, field, enum, macro, etc.). It introduces three comment positions (leading, inline on the same line, and trailing on the following line), a strict blank-line rule that prevents misattribution, and a fixed priority order for picking the comment that ends up in the generated Go code. The same rules apply to every symbol kind, macros included.

Motivation

C/C++ headers document symbols in many different styles. Some put the comment above the declaration, some at the end of the same line, and some on the line below. Without a precise rule, a generator can:

  • attach a comment to the wrong symbol (for example, the comment that actually documents the next declaration),
  • drop comments that were clearly intended for a symbol, or
  • behave inconsistently between symbol kinds.

A single, simple, predictable rule set makes the generated bindings' documentation reliable and makes the behavior easy to explain and test.

Terminology

Three comment positions are recognized relative to a declaration. The examples use gzgetc, but the rules apply to every symbol kind.

Leading comment — a comment immediately before the declaration:

// Read one byte, falling back to the real function.
int gzgetc(gzFile file);

Inline comment — a comment on the same line, after the declaration:

int gzgetc(gzFile file); // Read one byte, falling back to the real function.

Trailing comment — a comment on the line immediately after the declaration:

int gzgetc(gzFile file);
// Read one byte, falling back to the real function.

The three positions apply to macros in the same way:

#define Z_OK 0 // Operation succeeded.

Rule 1: A blank line breaks attribution

To avoid attributing a comment to the wrong symbol, a comment is associated with a declaration only if there is no blank line between them. If a blank line separates the comment from the declaration, the comment is not considered to belong to that declaration.

Both of the following declarations are treated as having no comment:

// Read one byte, falling back to the real function.

int gzgetc(gzFile file);

int gzgetc(gzFile file);

// Read one byte, falling back to the real function.

Rule 2: Resolution order

To obtain the comment for a symbol declaration:

  1. If a leading comment exists, use it.
  2. Otherwise, if an inline comment exists, use it.
  3. Otherwise, use the trailing comment, if any.
  4. If none of the above exist, the symbol has no comment.
Symbol kind Priority (highest first)
All symbols (including macros) leading → inline → trailing

Only one comment is chosen per symbol; lower-priority comments are ignored when a higher-priority one exists. For example, in:

// Leading doc.
int gzgetc(gzFile file); // Inline doc.
// Trailing doc.

the comment used for gzgetc is Leading doc..

Scope

The rules apply uniformly to all symbol kinds that llcppg converts, including:

  • types (struct, union, typedef, class, and so on)
  • functions and methods
  • variables
  • struct/class fields
  • enums and enum members
  • macros

Compatibility

Declarations that already use a leading comment with no blank line keep working exactly as before. Declarations whose comments are separated from them by a blank line will no longer pick up that comment, which is intentional: the blank line is the signal that the comment is not about this symbol.

Testing

Test cases should cover, for each applicable symbol kind (macros included):

  • leading only, inline only, and trailing only
  • each pairwise and the three-way combination, verifying the priority order
  • a blank line between a comment and the declaration, on either side, resulting in no comment
Ngôn ngữ chính
Go
Star
39
Fork
13
Merge trung bình
1 giờ 33 phút
Pull request đã merge (30 ngày)
256

Chuẩn bị môi trường

Dự án này không cung cấp dev container, Dockerfile hay hướng dẫn đóng góp, nên bạn cần tự thiết lập môi trường: hãy bắt đầu từ README và xem hướng dẫn đóng góp lần đầu của chúng tôi để biết các bước chung.

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 goplus/llcppg

Tất cả issue của goplus/llcppg

Issue tương tự

Thêm issue về Go

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.