Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

Proposal: Comment Attribution Rules for Symbol Declarations

Cerrado
  • ¿Algo no está bien?
#1,056 6 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
15/100
Tipo de issue
Nueva funcionalidad
Claridad
Bastante claro
Estado de actividad
Activo
Stack tecnológico
c, cpp, go
Área
documentation, tooling

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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
Lenguaje dominante
Go
Estrellas
41
Forks
13
Merge medio
2 h 17 min
PR fusionados (30 d)
178

Preparar el entorno

Este proyecto no incluye contenedor de desarrollo, Dockerfile ni guía de contribución, así que la configuración corre por tu cuenta: empieza por su README y consulta nuestra guía para la primera contribución para los pasos generales.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de goplus/llcppg

Todos los issues de goplus/llcppg

Issues similares

Más issues de Go

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.