Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

Proposal: Comment Attribution Rules for Symbol Declarations

Aperta
  • Qualcosa non va?
#1,056 6 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
15/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
c, cpp, go
Ambito
documentation, tooling

Direzione di ricerca

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.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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
Lingua principale
Go
Stelle
39
Fork
13
Merge medio
1h 33m
PR unite (30g)
256

Preparare l'ambiente

Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di goplus/llcppg

Tutte le issue di goplus/llcppg

Issue simili

Altre issue su Go

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.