Module 7 API Reference

Comparative Articles

Module 7: API Reference

Comparative Articles — Your Confusion-Resolving Documentation

Every mature language ecosystem has reference docs. Python has its docs. JavaScript has MDN. Rust has docs.rs. When you can't remember the difference between slice() and splice(), you don't guess — you look it up.

Mandarin has its own set of "wait, which one do I use?" pairs. Words that all translate to the same English word but have distinct, non-interchangeable meanings. This module is your MDN. Bookmark it. Come back when you're confused. Each entry is a deep-dive comparison with clear rules for when to use which. 

// This module is pure reference. No new grammar patterns.
// Think of it as:
//   man chinese-synonyms
//   docs.mandarin.io/api/confusing-pairs

// When you're writing Chinese and thinking "can I use X here?"
// look it up below. Ctrl+F is your friend.

1. 会 vs 能 vs 可以 — Three Flavors of "Can"

English has one word for "can." Mandarin has three, and they aren't interchangeable. If you've ever worked with authorization systems, this will click immediately. 

// Three types of "can" — mapped to system concepts:

会 (huì)   = SKILL          // A learned, acquired ability
             // "I installed this capability"
             // Like: hasSkill("swimming") → true

能 (néng)  = CAPABILITY     // Physical ability or circumstances allow it
             // "The system is capable / conditions permit"
             // Like: systemCheck() → canProceed

可以 (kěyǐ) = PERMISSION   // Allowed to do it
             // "Authorization granted"
             // Like: hasPermission("sit_here") → true

会 — Learned ability

Use 会 when someone has learned how to do something. It's an installed skill — something that took training to acquire. If you had to practice it, it's 会.

Chinese Pinyin Analogy English
我会说中文。 Wǒ huì shuō zhōngwén. I.hasSkill("chinese") I can speak Chinese.
她会游泳。 Tā huì yóuyǒng. she.hasSkill("swim") She can swim.
他会做饭。 Tā huì zuò fàn. he.hasSkill("cook") He can cook.

能 — Ability / circumstances permit

Use 能 when circumstances, physical ability, or conditions make something possible. It's not about whether you learned it — it's about whether the system can handle it right now.

Chinese Pinyin Analogy English
我明天能来。 Wǒ míngtiān néng lái. schedule.isAvailable(tomorrow) I can come tomorrow.
他能吃十个饺子。 Tā néng chī shí ge jiǎozi. he.capacity("dumplings") >= 10 He can eat ten dumplings.
这个箱子能放三本书。 Zhège xiāngzi néng fàng sān běn shū. box.capacity >= 3 This box can hold three books.

可以 — Permission

Use 可以 when asking or granting permission. This is your authorization layer. "Am I allowed to?"

Chinese Pinyin Analogy English
我可以坐这里吗？ Wǒ kěyǐ zuò zhèlǐ ma? auth.check("sit", here) Can I sit here?
这里不可以抽烟。 Zhèlǐ bù kěyǐ chōuyān. policy.denied("smoke", here) You can't smoke here.
我可以用你的手机吗？ Wǒ kěyǐ yòng nǐ de shǒujī ma? requestAccess("phone", owner) Can I use your phone?
The decision tree: "Did you learn this ability?" → 会. "Are conditions/physics allowing it?" → 能. "Are you allowed?" → 可以. Think of it as: hasSkill() vs systemCheck() vs hasPermission(). Overlap exists — you'll sometimes hear 能 used for permission too — but these defaults will keep you correct 90% of the time.

2. 了 vs 过 — Completion vs Experience

You met both of these in Module 3. Here's the deeper comparison you need when writing real sentences. Both go after verbs. Both relate to things that happened. But they answer different questions. 

// Git analogy:

了 (le)  = The latest commit.
           "This specific action completed."
           git log -1

过 (guò) = The entire commit history.
           "This has happened at some point in the past."
           git log --all
Chinese Pinyin Focus English
我吃了。 Wǒ chī le. Specific event completed I ate. (just now / a specific time)
我吃过。 Wǒ chī guò. Life experience I've eaten [that] (before, at some point).
我去了北京。 Wǒ qù le Běijīng. This specific trip happened I went to Beijing. (a specific trip)
我去过北京。 Wǒ qù guò Běijīng. It's in my history I've been to Beijing. (at some point in life)
我看了那个电影。 Wǒ kàn le nàge diànyǐng. The viewing completed I watched that movie. (e.g., last night)
我看过那个电影。 Wǒ kàn guò nàge diànyǐng. It's in my viewing history I've seen that movie (before).
When someone asks 你吃过吗？ they're asking about your life experience — "Have you ever...?" Answer with 吃过 or 没吃过. If they ask 你吃了吗？, they're asking about a specific recent event — "Did you eat (lunch/dinner)?" The particle changes the entire question.

3. 知道 vs 认识 vs 了解 — Three Ways to "Know"

English overloads "know" the way JavaScript overloads ==. You "know" a fact. You "know" a person. You "know" a topic deeply. Mandarin gives each one its own function. 

// Three functions — zero ambiguity:

知道 (zhīdào) = knowsFact()
                // You possess this piece of information.
                // "I know the answer." "I know where it is."

认识 (rènshi) = knowsEntity()
                // You're acquainted with a person or can recognize something.
                // "I know him." "I recognize this character."

了解 (liǎojiě) = understands()
                  // Deep familiarity. You really get it.
                  // "I understand this framework inside and out."
Chinese Pinyin Function English
我知道。 Wǒ zhīdào. knowsFact() I know. (a fact / piece of info)
我知道他的名字。 Wǒ zhīdào tā de míngzi. knowsFact("his_name") I know his name.
我认识他。 Wǒ rènshi tā. knowsEntity(him) I know him. (we've met)
我认识这个字。 Wǒ rènshi zhège zì. recognizes(char) I recognize this character.
我很了解中国。 Wǒ hěn liǎojiě Zhōngguó. understands("China", deep) I know China well. (deep understanding)
我想了解一下这个公司。 Wǒ xiǎng liǎojiě yíxià zhège gōngsī. explore("company") I'd like to learn more about this company.
The trap: "I know him" in English is ambiguous. In Chinese it's not. 我知道他 = I know about him (I've heard of him, I know facts about him). 我认识他 = I know him personally (we've met, I can pick him out of a crowd). 我了解他 = I understand him (I know what makes him tick). Three levels. Three functions. No overloading.

4. 对 vs 向 vs 往 — Direction Words

All three translate to "toward" in English. In Mandarin, they encode different types of directionality, like how a network request has a target, a direction, and a route. 

// Three "toward" — three different concepts:

对 (duì)   = target
             // The action is directed AT someone/something.
             // Like: sendRequest({ target: "server" })

向 (xiàng) = direction
             // The action moves in a direction or is oriented toward something.
             // Like: sendRequest({ direction: "north" })

往 (wǎng)  = heading
             // Physical movement toward a destination.
             // Like: navigate({ heading: "airport" })
Chinese Pinyin Type English
他对我很好。 Tā duì wǒ hěn hǎo. target — directed at me He's very nice to me.
对不起！ Duìbuqǐ! target — facing you Sorry! (lit: can't face [you])
我向他学习。 Wǒ xiàng tā xuéxí. direction — learning toward I learn from him.
向左走。 Xiàng zuǒ zǒu. direction — oriented left Go left. / Walk to the left.
往北走。 Wǎng běi zǒu. heading — physically heading north Go north. / Head north.
往前走。 Wǎng qián zǒu. heading — physically heading forward Go straight ahead.
Quick rule of thumb: 对 = who or what the action is aimed at (a person, a topic). 向 = which direction the action faces (can be abstract). 往 = where you're physically going (almost always with movement verbs). If you're giving driving directions, use 往. If you're talking about someone's attitude, use 对. If you're pointing in a general direction, use 向.

5. 看 vs 见 vs 看见 vs 看看 — Seeing and Looking

This family of words demonstrates two important Chinese patterns: verb + result compounds and verb reduplication. English smashes "look" and "see" together casually. Chinese separates intention from result. 

// The "seeing" API:

看 (kàn)     = look()
               // The intentional act of directing your eyes.
               // You're trying to see. No guarantee of result.

见 (jiàn)    = seen()    // (result marker)
               // The result of seeing. You perceived it.
               // Rarely used alone in modern speech.

看见 (kànjiàn) = look().then(seen)
               // You looked AND successfully saw.
               // Action + result. A resolved promise.

看看 (kànkan)  = look({ casual: true })
               // "Take a look." Softened, casual reduplication.
               // Like a polite, low-pressure request.
Chinese Pinyin Pattern English
我在看电视。 Wǒ zài kàn diànshì. Intentional action I'm watching TV.
你看！ Nǐ kàn! Directing attention Look!
我看见他了。 Wǒ kànjiàn tā le. Action + result I saw him. (looked and perceived)
我没看见。 Wǒ méi kànjiàn. Action + failed result I didn't see (it). (looked but didn't perceive)
我看看。 Wǒ kànkan. Casual reduplication Let me take a look.
明天见！ Míngtiān jiàn! Result as standalone See you tomorrow!
Reduplication is a pattern, not a special case. You can do this with many verbs to soften them into casual requests: 试 → 试试 (give it a try), 想 → 想想 (think about it), 说 → 说说 (tell me about it). It's like passing { force: false, polite: true } as options.

6. Quick Reference Table

Your cheat sheet. Print it, screenshot it, alias lookup="open api-reference.html". When in doubt, scan this table.

English Mandarin Options Rule
"can" 会 Learned skill — hasSkill()
能 Physical / circumstantial ability — systemCheck()
可以 Permission — hasPermission()
"completed" vs "experienced" 了 Specific event completed — git log -1
过 Life experience — git log --all
"know" 知道 Know a fact — knowsFact()
认识 Know a person / recognize — knowsEntity()
了解 Understand deeply — understands()
"toward" 对 Directed at a target — target
向 Direction of action — direction
往 Physical movement — heading
"see / look" 看 Intentional looking — look()
见 Result of seeing — seen()
看见 Looked and saw — look().then(seen)
看看 Casual look — look({ casual: true })
This is living documentation. You're not expected to memorize all of this in one pass. The goal is to know that these distinctions exist so you reach for the right word instead of defaulting to the first translation Google gives you. Revisit this page. The distinctions will sharpen with practice. Like any good API docs, you'll stop needing them once the patterns become muscle memory — but until then, keep this tab open.

Practice what you learned

Debug This Sentence Type Check Compile Check Flashcard Review