Foundations of API Design chapter #2994

tall-vase · 2025-12-05T13:29:11Z

Includes most of chapter 1 of foundations of API Design for Idiomatic Rust. Brought in from the gdoc. Tests have not been run locally yet, formatting has.

gribozavr · 2025-12-05T14:21:59Z

src/idiomatic/foundations-api-design/clarity-readability.md is being added, but it is empty and it is not linked from SUMMARY.md. Delete it?

(GitHub does not allow me to leave a comment on an empty file)

gribozavr · 2025-12-05T14:20:13Z

src/idiomatic/foundations-api-design.md

@@ -0,0 +1,3 @@
+---
+minutes: 2
+---


Do you intend to add something here?

Compare: https://github.com/google/comprehensive-rust/blob/main/src/idiomatic/leveraging-the-type-system.md?plain=1

At the very least, a title and {{%segment outline}} are needed.

gribozavr · 2025-12-05T14:28:44Z

src/idiomatic/foundations-api-design/meaningful-doc-comments.md

+It's important to write doc comments that developers will appreciate reading,
+that gives them the information they are looking for and doesn't just re-state
+the obvious.


Suggested change

It's important to write doc comments that developers will appreciate reading,

that gives them the information they are looking for and doesn't just re-state

the obvious.

Good doc comments provide information that the code, names, and types

cannot, without restating the obvious information.

More concise wording; more actionable ("information they are looking for" - not very actionable); more common spelling ("restate");.

gribozavr · 2025-12-05T14:30:17Z

src/idiomatic/foundations-api-design/meaningful-doc-comments/avoid-redundancy.md

+Function names and type signatures already document some information, avoid
+repeating them!


Suggested change

Function names and type signatures already document some information, avoid

repeating them!

Names and type signatures communicate a lot of information, don't repeat it in comments!

gribozavr · 2025-12-05T14:31:06Z

src/idiomatic/foundations-api-design/meaningful-doc-comments/avoid-redundancy.md

+/// Parses an ipv4 from a str. Returns an option for failure modes.
+fn parse_ip_addr_v4(input: &str) -> Option<IpAddrV4> { ... }
+
+// TODO: couple more of these, for the instructor to go through with students.


My favorite:

struct BusinessAsset { /// The customer id. let customer_id: u64, }

gribozavr · 2025-12-05T14:34:11Z

src/idiomatic/foundations-api-design/meaningful-doc-comments/avoid-redundancy.md

+```
+
+<details>
+- Motivation: Documentation that repeats name/signature information provides nothing new to the API user.


Suggested change

- Motivation: Documentation that repeats name/signature information provides nothing new to the API user.

- Motivation: Documentation that merely repeats name/signature information provides nothing new to the API user.

gribozavr · 2025-12-05T20:53:16Z

src/idiomatic/foundations-api-design/meaningful-doc-comments/who-are-you-writing-for.md

+```
+
+<details>
+- Motivation: It can be easy to fall into a pattern of writing only for you, but most documentation is for people coming in with a different perspective.


Suggested change

- Motivation: It can be easy to fall into a pattern of writing only for you, but most documentation is for people coming in with a different perspective.

- Background: The [curse of knowledge](https://en.wikipedia.org/wiki/Curse_of_knowledge) is a cognitive bias where experts assume that others have the same level of expertise and perspective.

- Motivation: Your reader does not have the same level of expertise and the same perspective as you. Don't write for people like yourself, write for others.

gribozavr · 2025-12-05T20:54:12Z

src/idiomatic/foundations-api-design/meaningful-doc-comments/who-are-you-writing-for.md

+
+```rust
+// TODO: What's a good illustration here?
+```


// expert writes for experts /// Canonicalizes the MIR for the borrow checker. /// /// This pass ensures that all borrows conform to the NLL-Polonius constraints /// before we proceed to MIR-to-LLVM-IR translation. pub fn canonicalize_mir(mir: &mut Mir) { // ... } // expert writes for newcomers /// Prepares the Mid-level IR (MIR) for borrow checking. /// /// The borrow checker operates on a simplified, "canonical" form of the MIR. /// This function performs that transformation. It is a prerequisite for the /// final stages of code generation. /// /// For more about Rust's intermediate representations, see the /// [rustc-dev-guide](https://rustc-dev-guide.rust-lang.org/mir/index.html). pub fn canonicalize_mir(mir: &mut Mir) { // ... }

gribozavr · 2025-12-05T20:58:47Z

src/idiomatic/foundations-api-design/meaningful-doc-comments/who-are-you-writing-for.md

+  much information.
+- Always ask: Is this documentation making it difficult for the API user? Are
+  they able to quickly grasp what they need or find out where they could need
+  it?


I'd also say something like "Experts also read API level documentation. Doc comments might not be the right place to educate your audience about the basics of your domain. In that case, signpost and namedrop - divert people to long-form documentation."

gribozavr · 2025-12-05T21:00:35Z

src/idiomatic/foundations-api-design/predictable-api.md

+
+# Predictable API
+
+Keep your APIs predictable through naming conventions and implementing common


Suggested change

Keep your APIs predictable through naming conventions and implementing common

Keep your APIs predictable by following naming conventions and implementing common

Parallel sentence structure.

gribozavr · 2025-12-05T21:01:02Z

src/idiomatic/foundations-api-design/predictable-api.md

+Keep your APIs predictable through naming conventions and implementing common
+traits.
+
+<!-- TODO -->


Some speaker notes would be nice. What is the framing for this section?

gribozavr

(misclick, I meant to simply "comment", but clicked "approve"; for clarity switching to "request changes")

Bring in existing foundations of API design work from google doc

9c1d7d1

tall-vase added the deep_dives/idiomatic label Dec 5, 2025

gribozavr approved these changes Dec 5, 2025

View reviewed changes

gribozavr requested changes Dec 5, 2025

View reviewed changes

		Function names and type signatures already document some information, avoid
		repeating them!

	Function names and type signatures already document some information, avoid
	repeating them!
	Names and type signatures communicate a lot of information, don't repeat it in comments!

	- Motivation: Documentation that repeats name/signature information provides nothing new to the API user.
	- Motivation: Documentation that merely repeats name/signature information provides nothing new to the API user.

-- Motivation: It can be easy to fall into a pattern of writing only for you, but most documentation is for people coming in with a different perspective.
+- Background: The [curse of knowledge](https://en.wikipedia.org/wiki/Curse_of_knowledge) is a cognitive bias where experts assume that others have the same level of expertise and perspective.
+- Motivation: Your reader does not have the same level of expertise and the same perspective as you. Don't write for people like yourself, write for others.


		# Predictable API

		Keep your APIs predictable through naming conventions and implementing common

	Keep your APIs predictable through naming conventions and implementing common
	Keep your APIs predictable by following naming conventions and implementing common

Foundations of API Design chapter #2994

Are you sure you want to change the base?

Foundations of API Design chapter #2994

Uh oh!

Conversation

tall-vase commented Dec 5, 2025

Uh oh!

gribozavr commented Dec 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gribozavr left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

gribozavr commented Dec 5, 2025 •

edited

Loading