improve documentation section

[ShahakShama]

Note

Low Risk
Documentation-only edits to the coding conventions; no runtime or behavioral code changes.

Overview
Updates style.md's documentation guidance by renaming the section to ## Documentation and clarifying the split between API docs (///) vs implementation comments (//).

Adds explicit rules for abbreviations vs acronyms in identifiers/docs, and expands the "trivial comments" guidance with stronger rationale plus new examples showing restatement vs "why" comments and when a short block-summary comment is acceptable (with a suggestion to extract helpers instead).

^{Written by Cursor Bugbot for commit d796251. This will update automatically on new commits. Configure here.}

[reviewable-StarkWare]

This change is 

[ShahakShama]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• allow unreachable, and expand when to use panic #13636
• add section when to return result #13635
• error types should have a Error suffix #13627
• add section on expect vs allow #13626
• delete combinators section #13416
• add section on test names #13276
• make short unit test into a recommendation #13275
• improve documentation section #13274 👈 (View in Graphite)
• remove track_caller sentence #13267
• remove sections of re-export #13266
• add logging section #13261 : 1 other dependent PR (#13262 )
• add instruction that TODOs should have an owner #13260
• add section advocating to use Self #13259
• add section on american english vs british english #13257
• remove section about private fields altogether #13166
• unite getter and setter sections, and modify setter section #13165
• reorder API sections (no text change) #13164
• add section saying that code inside macro should be formatted #13163
• add section on future returning pending #13162
• improve ai section #13147
• improve casting section #13146
• make the example in combinators compile #13145
• add comment in return value section to split checking the value and performing action to 2 lines #13144
• remove bad example in foo_or_else section #13141
• improve the starting paragraphs of testing section #13139
• improve macros section #13137
• remove unnecessary misc sections #13131
• reorder sections (move AI and Testing up) #13118
• remove open issues section #13115
• improve external dependencies section #13114
• remove github smell testing section #13113
• create misc section, move stuff into it, and order by importance (no erasure of anything yet) #13112
• change file layout section #13078
• add section on sleep in tests #13073
• add section on dependency injection #13072
• move expect message to a separate section with more explanation #13071
• add directory layout section #12950
• rename allocations and add &Option<T> #12781
• remove laziness  #11591
• rewrite types section #11588
• more comments  #11587
• more comments  #11586
• more comments  #11585
• more comments  #11584
• arithmetic: remove ditto for other mathematical operations. #11848
• gilad/style-guide

This stack of pull requests is managed by Graphite. Learn more about stacking.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

[Stavbe]

is this --- do something or it is just an AI footprint

@Stavbe made 10 comments.
Reviewable status: 0 of 1 files reviewed, 9 unresolved discussions (waiting on ShahakShama).

---

style.md line 368 at r2 (raw file):

## Documentation

Make sure every struct, enum, member, function, method and enum variant that's part of the API is documented --- Unless there's nothing to add that the name didn't cover

,

Code quote:

---

---

style.md line 370 at r2 (raw file):

Make sure every struct, enum, member, function, method and enum variant that's part of the API is documented --- Unless there's nothing to add that the name didn't cover

Use `///` to document the API --- for the user.

remove

Code quote:

--- for the user.

---

style.md line 372 at r2 (raw file):

Use `///` to document the API --- for the user.

Use `//` to explain how the code works --- for someone reading the internal implementation.

removeb

Code quote:

---

---

style.md line 376 at r2 (raw file):

Don't use `/* */` - style comments.

If you want to use an abbreviation (e.g. `tx` for `transaction`) or acronym (e.g. `ABI` for `Application Binary Interface`), introduce it in the documentation of the struct/enum the abbreviation/acronym shortens.

Do we want people to write tx = transaction in the enum definition ? It is weird... maybe -make sure the fielde documented with the "full" word.

---

style.md line 388 at r2 (raw file):

Take extra care when using AI-generated code, which tends to include a lot of trivial comment-bloat.

**Rationale**: clear code is self-documenting; repeating it wastes the reader's time and adds maintenance burden, as the comment can drift out of sync with the code it describes.

I think we want to avoid this, say, because we want to encourage people to do.

Code quote:

**Rationale**: clear code is self-documenting; repeating it wastes the reader's time and adds maintenance burden, as the comment can drift out of sync with the code it describes.

---

style.md line 397 at r2 (raw file):

// BAD - Restates the function signature.
/// Returns the user's name.
fn user_name(&self) -> &str { ... }

I think this bsd needs to be removed because we encourage documenting also "obvious" functions.

Code quote:

// BAD - Restates the function signature.
/// Returns the user's name.
fn user_name(&self) -> &str { ... }

---

style.md line 405 at r2 (raw file):

However, a comment that gives a title to a paragraph of code is useful --- it tells the reader what the block achieves so they can skim or skip it.

remove

Code quote:

---

---

style.md line 423 at r2 (raw file):

When you find yourself adding such a title comment, consider extracting the paragraph into a helper function where it makes sense --- the function name then serves as the documentation.

remove

Code quote:

--- the function name then serves as the documentation.

[ShahakShama]

@ShahakShama made 7 comments.
Reviewable status: 0 of 1 files reviewed, 8 unresolved discussions (waiting on Stavbe).

---

style.md line 370 at r2 (raw file):

Previously, Stavbe wrote…

remove

I like the for the user section. Changed to parentheses

---

style.md line 372 at r2 (raw file):

Previously, Stavbe wrote…

removeb

Done.

---

style.md line 376 at r2 (raw file):

Previously, Stavbe wrote…

Do we want people to write tx = transaction in the enum definition ? It is weird... maybe -make sure the fielde documented with the "full" word.

I mainly thought of the acronym section when writing this. how's this now?

---

style.md line 388 at r2 (raw file):

Previously, Stavbe wrote…

I think we want to avoid this, say, because we want to encourage people to do.

I disagree. Lior also said that this rationale is true. If you want we can bring this to discussion

---

style.md line 397 at r2 (raw file):

Previously, Stavbe wrote…

I think this bsd needs to be removed because we encourage documenting also "obvious" functions.

I disagree. I also wrote this at the top of the documentation section (Unless there's nothing to add that the name didn't cover)

---

style.md line 405 at r2 (raw file):

Previously, Stavbe wrote…

remove

I do want a non-comma separator. How's this?

---

style.md line 423 at r2 (raw file):

Previously, Stavbe wrote…

remove

Done.

[ShahakShama]

@ShahakShama made 1 comment.
Reviewable status: 0 of 1 files reviewed, 8 unresolved discussions (waiting on Stavbe).

---

style.md line 368 at r2 (raw file):

Previously, Stavbe wrote…

,

Done.

[Stavbe]

@Stavbe made 1 comment and resolved 6 discussions.
Reviewable status: 0 of 1 files reviewed, 3 unresolved discussions (waiting on ShahakShama).

---

style.md line 379 at r4 (raw file):

### Abbreviations and Acronyms
Abbreviations (e.g. `tx` for `transaction`) are allowed only in variables, function arguments and function names. Prefer to avoid them in function names if possible.

This is confusing. It is always possible. Let's choose yes or no- I vote for yes.

Code quote:

and function names. Prefer to avoid them in function names if possible.