google / google/zerocopy

Update our use of the term "layout"

Open
#439 0 comments 0 reactions 0 assignees View on GitHub
compatibility-nonbreaking
Dominant language
Rust
Stars
2.6k
Forks
179
Avg merge
1d 19h
Merged PRs (30d)
29

Description

As of [this PR](https://github.com/rust-lang/unsafe-code-guidelines/pull/457/files#diff-3d27114a58daccf7b7133bf5d8552c310e4399a5f4df29fe8eefcef7e4ec18ceR115-R117), the Rust reference defines the term "layout" as:

> The *layout* of a type defines its size and alignment as well as the offsets of its subobjects (e.g. fields of structs/unions/enums/... or elements of arrays, and the discriminant of enums).
>
> Note that layout does not capture everything that there is to say about how a type is represented on the machine; it notably does not include ABI or Niches.

Our existing documentation and comments use the term "layout" to refer only to a type's size and alignment. We should update our usage to be consistent with this definition.

Tasks:

- [ ] Find any location where we use the term "layout"
- [ ] Make sure its use is consistent with this definition. A few considerations:
- In doc comments, it may be appropriate (depending on context) to link to this definition
- In some contexts, it may be appropriate to call out that field offsets are included in the definition (many readers will not be familiar with the precise definition)
- We must not use "layout" in a context in which we _don't_ mean to include field offsets. In such cases, we should explicitly say "size and alignment" or similar.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.