rust-lang / rust-lang/rust-bindgen

Extraneous leading lower-than character (<) in after-member comment syntax

Open
#3,172 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Rust
Stars
5.3k
Forks
829
Avg merge
1d 1h
Merged PRs (30d)
15

Description

Context

Some C code may declare doc comments in the same line as the respective member with a special syntax for the effect.

enum ColorSpace {
    RGB = 0, /**< red green blue */
    YBR_FULL, /**< YCbCr, full chrominance */
    XYB = 2 /**< LMS XYB */
};

This seems to be correctly interpreted, as bindgen is associating these comment blocks with the correct item. Removing < from the input would have resulted in the comments being linked to the subsequent item. However, the leading < character is retained in the Rust doc comment.

/* automatically generated by rust-bindgen 0.71.1 */

#[doc = "< red green blue"]
pub const ColorSpace_RGB: ColorSpace = 0;
#[doc = "< YCbCr, full chrominance"]
pub const ColorSpace_YBR_FULL: ColorSpace = 1;
#[doc = "< LMS XYB"]
pub const ColorSpace_XYB: ColorSpace = 2;
pub type ColorSpace = ::std::os::raw::c_uint;
Expected behavior

Since the < is part of the comment syntax, it should not be included in the doc string.

/* automatically generated by rust-bindgen 0.71.1 */

#[doc = "red green blue"]
pub const ColorSpace_RGB: ColorSpace = 0;
#[doc = "YCbCr, full chrominance"]
pub const ColorSpace_YBR_FULL: ColorSpace = 1;
#[doc = "LMS XYB"]
pub const ColorSpace_XYB: ColorSpace = 2;
pub type ColorSpace = ::std::os::raw::c_uint;

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reproducing the shown C enum with bindgen 0.71.1 and inspect the generated Rust documentation strings. Trace how after-member comments are associated with declarations, then verify that the generated docs omit the leading < while remaining attached to the correct constants.

Written by the indexing model from the issue text.

Assessment

Tech stack
c, rust
Domain
tooling
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.