rust-lang / rust-lang/rust

rustdoc-json: Include size, alignment, and field offset info for types

Open
#142,201 8 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

A-rustdoc-json C-feature-request T-rustdoc
Dominant language
Rust
Stars
119k
Forks
16.1k
PR merge metrics
PR metrics pending

Description

Size, alignment, and field offset are often part of types' public API, so it would be lovely to make that information available in rustdoc JSON (and perhaps in rustdoc HTML as well, when relevant).

For example, public repr(C) types have well-defined layout which may be depended on by FFI use cases:

#[repr(C)]
pub struct Example {
    first: i64,
    pub second: Option<&'static str>,
}

Say the type of first were to change from i64 to (i64, i64). Since the first field is not public, there's no SemVer hazard from the field access. However, there are two hazards that cargo-semver-checks cannot detect without knowing size, alignment, and offset information:

  • The offset of second changes from 8 to 16 (IIUC), so applications using Example via FFI need to update where they find that field's information.
  • The size of the Example struct grows by 16 bytes, which likely affects how it can be allocated as well as the layout of [Example; N] arrays and slices thereof.

Similar information is useful when considering whether #[repr(transparent)] is public API. The current rule is that it's public API if its sole non-1-ZST field is pub. cargo-semver-checks would like to be able to:

  • Clearly determine whether fields are 1-ZST or not.
  • Thereby deduce whether #[repr(transparent)] is public API or not.
  • In cases where #[repr(transparent)] used to be and has since stopped being public API, report to the user the reason why #[repr(transparent)] is no longer public API. This point in particular cannot be addressed if rustdoc performs 1-ZST analysis and strips #[repr(transparent)] in cases where it is considered non-public.

@rustbot label A-rustdoc-json

cc @aDotInTheVoid per our conversation at RustWeek

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 examining the rustdoc JSON representation of public types and the existing handling of repr(C) and repr(transparent); the issue does not name specific files or tests. Done means exposing size, alignment, and field-offset information in rustdoc JSON, with any relevant rustdoc HTML treatment decided, and supporting 1-ZST analysis for transparent types.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
compilers, documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.