Add API documentation Chinese version

[aherman3]

Summary by CodeRabbit

• New Features
  • Introduced comprehensive documentation for Wechaty, detailing technical aspects of classes and APIs such as Contact, ContactSelf, Friendship, Message, Room, and Wechaty itself.
  • Added new guides and examples for using various Wechaty functionalities, including managing contacts, handling messages, dealing with friend requests, and interacting with chat rooms.
  • Provided detailed documentation on the Wechaty class, explaining different types of Puppets and their purposes.
• Documentation
  • Updated and reorganized the Wechaty library documentation, enhancing class and method descriptions with practical examples.

[coderabbitai]

Walkthrough

This update introduces comprehensive documentation for Wechaty, focusing on providing bilingual support and enriching the API documentation. It includes technical details on various classes such as Contact, Message, Room, and Wechaty itself, along with methods and usage examples aimed at facilitating both English and Chinese-speaking users. The effort reflects a significant enhancement in accessibility and usability of Wechaty's documentation.

Changes

Files	Change Summary
overview.mdx, .../api/contact-self.md, .../api/contact.md, .../api/friendship.md, .../api/message.md, .../api/overview.mdx, .../api/room-invitation.md, .../api/room.md, .../api/wechaty-class.md, .../api/wechaty.md	Introduced and updated comprehensive documentation for Wechaty's API, including classes and methods with examples.

Related issues

• wechaty doc update #1512: The extensive updates and enhancements in Wechaty's documentation could address the objectives of making the documentation bilingual and more accessible, as outlined by the user's plan to update Wechaty's API documentation.

🐰✨

In the land of code, where the snippets roam,
A rabbit worked hard, making documentation home.
With each line and example, the knowledge tree grew,
From English to Chinese, understanding flew.

📚🌍

Now, with docs in hand, developers smile,
As Wechaty's secrets, are clear, sans guile.
Cheers to the rabbit, whose efforts we admire,
Lighting up the path, with documentation fire!

🎉🐇✨

Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media?

Share

• X
• Mastodon
• Reddit
• LinkedIn

---

Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>.
  • Generate unit-tests for this file.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
  • @coderabbitai generate unit tests for this file.
  • @coderabbitai modularize this function.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai generate interesting stats about this repository and render them as a table.
  • @coderabbitai show all the console.log statements in this repository.
  • @coderabbitai read src/utils.ts and generate unit tests.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (invoked as PR comments)

• @coderabbitai pause to pause the reviews on a PR.
• @coderabbitai resume to resume the paused reviews.
• @coderabbitai review to trigger a review. This is useful when automatic reviews are disabled for the repository.
• @coderabbitai resolve resolve all the CodeRabbit review comments.
• @coderabbitai help to get help.

Additionally, you can add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.

CodeRabbit Configration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• The JSON schema for the configuration file is available here.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/coderabbit-overrides.v2.json

CodeRabbit Discord Community

Join our Discord Community to get help, request features, and share feedback.

[coderabbitai]

Review Status

Actionable comments generated: 4

Configuration used: CodeRabbit UI

Commits

Files that changed from the base of the PR and between 87f96e9 and eb2274d.

Files ignored due to path filters (2)

• docusaurus/npm-debug.log is excluded by: !**/*.log
• package.json is excluded by: !**/*.json

Files selected for processing (10)

• docusaurus/i18n/references/overview.mdx (1 hunks)
• docusaurus/i18n/zh/docusaurus-plugin-content-docs/current/api/contact-self.md (1 hunks)
• docusaurus/i18n/zh/docusaurus-plugin-content-docs/current/api/contact.md (1 hunks)
• docusaurus/i18n/zh/docusaurus-plugin-content-docs/current/api/friendship.md (1 hunks)
• docusaurus/i18n/zh/docusaurus-plugin-content-docs/current/api/message.md (1 hunks)
• docusaurus/i18n/zh/docusaurus-plugin-content-docs/current/api/overview.mdx (1 hunks)
• docusaurus/i18n/zh/docusaurus-plugin-content-docs/current/api/room-invitation.md (1 hunks)
• docusaurus/i18n/zh/docusaurus-plugin-content-docs/current/api/room.md (1 hunks)
• docusaurus/i18n/zh/docusaurus-plugin-content-docs/current/api/wechaty-class.md (1 hunks)
• docusaurus/i18n/zh/docusaurus-plugin-content-docs/current/api/wechaty.md (1 hunks)

Additional comments: 55

docusaurus/i18n/zh/docusaurus-plugin-content-docs/current/api/wechaty-class.md (2)

• 5-7: The explanation of the Wechaty class and its dependency on the Puppet implementation is clear and concise. However, it might be beneficial to include a brief description of what a Puppet is for readers who might not be familiar with the concept.

Consider adding a short explanation of what a Puppet is and how it affects the functionality of a Wechaty instance.

• 9-11: The link provided to learn more about Puppets in Wechaty is helpful. However, ensure that the link is accessible and the content is up-to-date to provide the best learning experience for the readers.

docusaurus/i18n/zh/docusaurus-plugin-content-docs/current/api/overview.mdx (1)

• 15-21: The introduction to the Wechaty API is clear and provides a good starting point for new users. However, the example provided is very minimal and might not be sufficient for a complete beginner to understand how to start using Wechaty.

Consider expanding the example to include a more comprehensive demonstration of a simple Wechaty bot, such as logging in and responding to a message, to provide a clearer starting point for new developers.

docusaurus/i18n/zh/docusaurus-plugin-content-docs/current/api/room-invitation.md (1)

• 17-34: The example provided for accepting a room invitation is clear and demonstrates the use of the accept() method effectively. However, it's important to remind developers to handle permissions and ensure that their bot is prepared to manage new room invitations appropriately.

Consider adding a note about checking permissions and managing room invitations responsibly to avoid spam or unintended behavior.

docusaurus/i18n/zh/docusaurus-plugin-content-docs/current/api/contact-self.md (2)

• 20-39: The method avatar([file]) is well-documented with a clear example. However, it might be helpful to explain the optional file parameter in more detail, such as when and why a developer might want to use it.

Consider adding more details about the file parameter for the avatar([file]) method, including example use cases where a developer might want to set a new avatar for the bot.

• 59-80: The documentation for signature(signature) method is clear and includes a practical example. However, it's important to mention any limitations or guidelines related to changing the bot's signature, such as length restrictions or content guidelines.

Consider adding a note about any limitations or guidelines for the bot's signature, to help developers understand what is allowed and to prevent errors.

docusaurus/i18n/zh/docusaurus-plugin-content-docs/current/api/friendship.md (12)

• 1-3: The metadata section correctly defines the title for the document. However, ensure consistency in document formatting across all documentation files for a unified look and feel.
• 5-5: The introduction provides a clear overview of the Friendship class's purpose within the Wechaty framework. It's concise and informative, making it accessible to Chinese-speaking developers.
• 7-7: Including a link to an example bot (friend-bot.ts) is a great way to provide practical context. Ensure this link remains valid and the example is up-to-date to prevent confusion.

Verification successful

---

The verification process has successfully confirmed the existence and validity of the friend-bot.ts example link provided in the documentation. The link responds with a "200" HTTP status code, indicating that it is accessible and valid.

Scripts Executed

The following scripts were executed for the analysis:

---

Script:

#!/bin/bash
# Verify the existence and validity of the friend-bot.ts example.
curl --head https://github.com/wechaty/wechaty/blob/1523c5e02be46ebe2cc172a744b2fbe53351540e/examples/friend-bot.ts | grep "200 OK"

Length of output: 450

---

---

Script:

#!/bin/bash
# Re-verify the existence and validity of the friend-bot.ts example with a more comprehensive approach.
curl -L -o /dev/null -sw "%{http_code}" https://github.com/wechaty/wechaty/blob/1523c5e02be46ebe2cc172a744b2fbe53351540e/examples/friend-bot.ts | grep '^2'

Length of output: 161

* 11-15: The summary of the `Friendship` class's capabilities is clear and well-structured, providing a quick overview of its functionalities. Consider adding more detail about the context in which each functionality is used for a deeper understanding. * 17-25: The method table is well-organized, offering a quick reference to the instance methods available in the `Friendship` class. Ensure that the return types are correctly linked or explained somewhere in the document for clarity. * 26-30: The static methods section is concise and follows the same format as the instance methods section, which is good for consistency. Similar to the instance methods, ensure that the return types are well-documented. * 32-62: The example provided for `friendship.accept()` is practical and demonstrates the method's usage effectively. However, ensure that the comments within the code are translated to Chinese to maintain consistency with the document's language.

Consider translating the inline comments in the code examples to Chinese for consistency with the document's primary language.

• 64-83: The friendship.hello() method description and example are clear and demonstrate the method's purpose well. As with the previous example, translating the comments to Chinese would improve consistency.

Translate the inline comments in the code examples to Chinese to maintain consistency with the document's language.

• 85-99: The friendship.contact() method description and example are concise and informative. Ensure that the example code comments are translated into Chinese for language consistency throughout the document.

Translate the inline comments in the code examples to Chinese for consistency.

• 101-126: The friendship.type() method description and example are informative. The enumeration of FriendshipType values provides clarity on the method's return type. Ensure all comments are in Chinese for consistency.

Translate the inline comments in the code examples to Chinese for consistency.

• 128-144: The Friendship.search(phone) method description is clear and includes an important note on best practices regarding rate limits. This is crucial information for developers to avoid potential issues with account suspension.
• 146-189: The Friendship.add(contact, options) method description and examples are comprehensive, covering different scenarios. The note on best practices regarding rate limits is repeated here, which is good for emphasis. Ensure all comments and strings in the examples are translated into Chinese for consistency.

Translate the inline comments and strings in the code examples to Chinese for consistency.

docusaurus/i18n/zh/docusaurus-plugin-content-docs/current/api/contact.md (10)

• 1-3: The metadata section correctly specifies the title of the document as "Contact Class". This is essential for proper indexing and display within the Docusaurus documentation site.
• 5-9: The introduction provides a brief overview of the Contact class, stating that all contacts (friends) are encapsulated as instances of the Contact class. This repetition helps reinforce the purpose of the class but could be condensed to improve readability.

Consider combining these sentences to avoid repetition and streamline the introduction.

• 10-10: The link to the Contact-Bot example is a valuable resource for developers, offering practical usage examples of the Contact class. Including such links enhances the documentation's utility.
• 24-39: The instance methods section is comprehensive, detailing various methods available on the Contact class instances. It's well-organized and provides a clear overview of the functionality each method offers.
• 40-45: The static methods section succinctly describes methods for finding individual or multiple contacts. This section is crucial for developers looking to query contacts programmatically.
• 47-53: The detailed explanation for the say method, including its parameters and the note on puppet compatibility, is informative. However, there's a minor issue with spacing around the method parameters in the documentation.

Consider adding spaces around the parameters for better readability.

• 55-108: The examples provided for various use cases of the say method are practical and cover a wide range of scenarios, including sending text, files, contact cards, URL links, and mini-programs. These examples are instrumental in helping developers understand how to use the Contact class effectively.
• 110-252: The documentation for other instance methods (name, alias, friend, type, gender, province, city, avatar, sync, self) is clear and concise, with examples provided for each method. This thoroughness ensures developers have the necessary information to utilize these methods effectively.
• 254-294: The static methods find and findAll are well-documented, with examples illustrating their usage. This section is crucial for developers looking to query contacts programmatically and is presented clearly.
• 296-307: The typedef section for ContactQueryFilter is a valuable addition, providing clarity on the options available for querying contacts. This section enhances the documentation by detailing the search capabilities of the Contact class.

docusaurus/i18n/zh/docusaurus-plugin-content-docs/current/api/message.md (19)

• 1-3: The metadata and title of the document are correctly formatted and provide clear information about the content.
• 8-28: The instance methods are well-organized in a table format, providing a quick overview of the available methods and their return types. Consider adding a brief description column to the table for even quicker reference.
• 39-61: The description and example for message.from() are clear and demonstrate how to retrieve the sender of a message. The example code is correctly formatted and easy to understand.
• 63-84: The description and example for message.to() accurately explain how to get the message recipient. The note about returning null in a room context is particularly helpful. The example code is well-structured and informative.
• 86-107: The description and example for message.room() effectively convey how to find out which room a message belongs to, if any. The example is clear and demonstrates practical usage within a conditional block.
• 109-130: The message.text() method description and example clearly explain how to retrieve the text content of a message. The example code is straightforward and demonstrates a common use case effectively.
• 132-148: The description and example for message.toRecalled() accurately describe how to retrieve the content of a recalled message. The example code is clear and demonstrates handling recalled messages effectively.
• 150-228: The message.say() method description and example comprehensively cover how to reply with text, contacts, files, links, and mini-programs. The examples are diverse, demonstrating multiple use cases and the flexibility of the say method. The note about puppet compatibility is crucial and well-placed.
• 230-253: The message.type() method description and example clearly explain how to determine the type of a message. The list of supported message types is helpful, and the example code demonstrates a practical use case.
• 255-266: The message.self() method description and example accurately describe how to check if a message was sent by the bot itself. The example code is simple and effectively demonstrates the method's usage.
• 268-284: The message.mention() method description and example clearly explain how to retrieve a list of contacts mentioned in a group message. The example code is straightforward and demonstrates the method's practical application.
• 286-297: The message.mentionSelf() method description and example effectively demonstrate how to check if the bot was mentioned in a group message. The example code is clear and provides a useful scenario for bot interaction in group chats.
• 299-320: The message.forward() method description and example accurately describe how to forward a message to another contact or room. The example code is well-structured and demonstrates a common use case for message forwarding.
• 322-324: The message.date() method description is concise and clearly explains how to retrieve the timestamp of when a message was sent.
• 326-329: The message.age() method description clearly explains how to calculate the age of a message in seconds, providing a practical example to illustrate the concept.
• 331-335: The message.toFileBox() method description accurately explains how to extract multimedia files from a message and store them in a FileBox. The note about puppet compatibility is important and well-placed.
• 337-341: The message.toContact() method description clearly explains how to extract forwarded contact card content and encapsulate it into a Contact type. The note about puppet compatibility is crucial for developers to understand the method's availability.
• 343-346: The message.toUrlLink() method description accurately explains how to extract URL links from a message and encapsulate them into a UrlLink class. The note about puppet compatibility is informative and necessary for developers to understand the method's applicability.
• 348-356: The static methods Message.find() and Message.findAll() are briefly described, providing an overview of their functionality to find messages in the cache. The descriptions are clear and concise, effectively conveying the purpose of these methods.

docusaurus/i18n/zh/docusaurus-plugin-content-docs/current/api/wechaty.md (5)

• 5-13: The introduction and classification of Wechaty Bots based on the Puppet being used (web-wechat, ipad-wechat, ios-wechat) are clear and concise. However, it's important to ensure that the terminology used is consistent with the official names of the platforms. For example, "web-wechat" might be more accurately referred to as "Web WeChat" to align with official branding.

Ensure that the terminology used in the documentation aligns with the official branding and naming conventions of the platforms and technologies mentioned.

• 17-17: The link provided to explain what a Puppet is in Wechaty is helpful for users unfamiliar with the concept. However, it's crucial to verify that this link is up-to-date and leads to a page that is maintained and contains accurate information.
• 47-53: The example provided for creating a Wechaty instance and handling basic events (scan, login, message) is a great way to introduce new users to the library. However, it's important to ensure that this example is tested and works as expected in the current version of Wechaty.

Ensure the example code snippet is up-to-date and functions correctly with the current version of Wechaty.

• 56-63: The documentation for event handling in Wechaty (on(event, listener)) is clear and provides a good overview of some basic events (scan, login, logout, message). Including examples for each event type is helpful. However, it would be beneficial to link to a more comprehensive list of events that Wechaty can handle, as this would provide developers with a better understanding of the library's capabilities.

Consider adding a link to a comprehensive list of Wechaty events or a section that details all available events and their descriptions. This will help developers discover and utilize the full range of functionalities offered by Wechaty.

• 284-304: The section on Wechaty.instance([options]) provides a useful example of obtaining a global instance of Wechaty and handling events. This is a valuable addition for developers looking to implement singleton patterns or manage a single instance across their application. However, it's crucial to highlight the implications of using a global instance, such as potential conflicts or issues with state management in larger applications.

Add a note or warning about the considerations and best practices when using Wechaty.instance([options]) to manage a global instance of Wechaty, especially in the context of larger applications or projects where state management and modularity are concerns.

docusaurus/i18n/zh/docusaurus-plugin-content-docs/current/api/room.md (3)

• 26-26: The method signature for say includes a mix of Chinese and English, which might be confusing. Consider using either English or Chinese consistently for parameters like text 或 Contact 或 File 或 Url. Additionally, the abbreviation "URL" should be in uppercase.

Consider revising the method signature to maintain consistency in language use and correct the abbreviation "URL".

• 59-59: The method name room.say and its parameters are described in a mix of Chinese and English. For clarity and consistency, consider using one language consistently throughout the documentation. Additionally, "UrlLink" and "MiniProgram" are technical terms that should remain in English to match the actual code.

Consider revising the method description to maintain consistency in language use and ensure technical terms match the actual code.

• 487-487: In the static method Room.create, the parameter contactList is mentioned. It's important to ensure that the parameter names in the documentation match those in the actual code for clarity and consistency.

Ensure that the parameter names used in the documentation accurately reflect those used in the codebase.

[coderabbitai]

In the description of the id property, the abbreviation for "identification" should be spelled in all uppercase as "ID" for consistency and correctness.

- 获取群ID。这个ID 是否是永久不变的ID 取决于使用哪一个puppet
+ 获取群ID。这个ID 是否是永久不变的ID 取决于使用哪一个puppet

---

Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation.

Suggested change

	| id | `string` | 获取群ID。这个ID 是否是永久不变的ID 取决于使用哪一个puppet，具体 查看puppet兼容性清单，参照 [puppet-compatible-table](https://wechaty.js.org/docs/specs/puppet/) |
	| id | `string` | 获取群ID。这个ID 是否是永久不变的ID 取决于使用哪一个puppet，具体 查看puppet兼容性清单，参照 [puppet-compatible-table](https://wechaty.js.org/docs/specs/puppet/) |

[coderabbitai]

The properties table is well-structured, providing clear information about the id property of a contact. However, there's a minor typographical issue with the abbreviation "ID".

- 获取联系人ID，这个ID 是否为永久唯一ID 取决于您使用什么puppet
+ 获取联系人ID，这个ID是否为永久唯一ID取决于您使用什么puppet

---

Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation.

Suggested change

	| 名称 | 类型 | 描述 |
	| :--- | :--- | :--- |
	| id | `string` | 获取联系人ID，这个ID 是否为永久唯一ID 取决于您使用什么puppet, 参照 [puppet-compatible-table](https://wechaty.js.org/docs/specs/puppet/) |
	| 名称 | 类型 | 描述 |
	| :--- | :--- | :--- |
	| id | `string` | 获取联系人ID，这个ID是否为永久唯一ID取决于您使用什么puppet, 参照 [puppet-compatible-table](https://wechaty.js.org/docs/specs/puppet/) |

[coderabbitai]

The documentation for the Wechaty class and its methods (start(), stop(), logout(), logonoff(), userSelf(), say()) is well-structured and provides a clear overview of the functionalities available. However, it would be beneficial to include more detailed descriptions for each method, especially for logonoff() and userSelf(), to explain their use cases and return values more comprehensively.

Consider expanding the descriptions for each method to include more details about their use cases, expected parameters, and return values. This will enhance the documentation's usefulness for developers.

[coderabbitai]

Tip

Codebase Verification

The verification process has confirmed that the files referenced by the links in the docusaurus/i18n/references/overview.mdx document do not exist at the specified paths. This indicates that the review comment is valid, as it emphasizes the importance of ensuring that all links are working and lead to the correct documentation pages to avoid confusion for the readers.

Analysis chain

The overview of Wechaty references is well-structured, providing a clear index to various important aspects of Wechaty documentation. However, ensure that all the links are working and lead to the correct documentation pages to avoid confusion for the readers.

---

Scripts Executed

The following scripts were executed for the analysis:

---

Script:

#!/bin/bash
# Verify the accessibility of all links.
links=(
  "../api/overview.mdx"
  "../../../docs/polyglot/overview.mdx"
  "../../../docs/puppet-providers/overview.mdx"
  "../../../docs/puppet-services/overview.mdx"
  "../../../docs/specs/overview.mdx"
)
for link in "${links[@]}"; do
  # Assuming a function check_link exists that returns non-zero for broken links
  check_link "$link" || echo "Broken link: $link"
done

Length of output: 1498

---

---

Script:

#!/bin/bash
# Verify the existence of files referenced by the links.
base_path="docusaurus/i18n/references"

# Convert the relative paths to paths relative to the repository root
links=(
  "docusaurus/i18n/api/overview.mdx"
  "docs/polyglot/overview.mdx"
  "docs/puppet-providers/overview.mdx"
  "docs/puppet-services/overview.mdx"
  "docs/specs/overview.mdx"
)

# Check each link for existence
for link in "${links[@]}"; do
  if [ ! -f "$link" ]; then
    echo "Missing file: $link"
  fi
done

Length of output: 1080