Skip to content

docs: say which fields a box exposes, and narrow the colon rule - #48

Merged
jo16oh merged 3 commits into
mainfrom
style/colon-rule
Sep 21, 2026
Merged

jo16oh merged 3 commits into
mainfrom
style/colon-rule

Conversation

@jo16oh

@jo16oh jo16oh commented Sep 21, 2026

Copy link
Copy Markdown
Owner

What changed

Traits

  • annotate the box sample with the field it reads, and say the Val's own fields are gone from it:
    p.id is a type error, because dyn drops the concrete type
  • a member may not take the name of a field the implementing Val holds, a field another trait on
    that Val requires included. That one is reported at implTrait, not at the declaration
  • move A trait is a contract between Vals above the defaults, where the brand is first at stake

The colon rule

The old rule kept a colon wherever the second half gave a reason or a detail, which covers most of
them, and the book ran one mid-sentence colon per eight sentences. The rule now reads what follows
the colon: a noun phrase naming what came before stays, a full clause becomes two sentences, and a
reason becomes because.

  • 26 sites across the book follow it. Two become because
  • the 9 that stay are all noun phrases, such as the shape: the fields every variant holds

- annotate the box sample with the field it reads, and say the Val's own
  fields are gone from it
- a member may not take the name of a field the Val holds, another trait's
  requirement included, reported at `implTrait`
- move `A trait is a contract between Vals` above the defaults, where the
  brand is first at stake
- a noun phrase naming what came before stays, a full clause becomes two
  sentences, and a reason becomes `because`
- the old rule kept a colon for any reason or detail, which covers most of
  them, and the docs run one mid-sentence colon per eight sentences
- 26 sites across the book, one per sentence pair
- two become `because`, where the colon carried the reason
- a noun phrase after the colon stays, such as the shape's field list
@jo16oh
jo16oh merged commit 7cd5833 into main Sep 21, 2026
2 checks passed
@jo16oh
jo16oh deleted the style/colon-rule branch September 24, 2026 14:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant