Add API documentation Chinese version #1531
Conversation
…room.md Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
…friendship.md Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
…wechaty-class.md Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
…friendship.md Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
…contact.md Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
…contact.md Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
…contact.md Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
…contact-self.md Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
…contact.md Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
WalkthroughThis 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 Changes
Related issues
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? TipsChatThere are 3 ways to chat with CodeRabbit:
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)
Additionally, you can add CodeRabbit Configration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Review Status
Actionable comments generated: 4
Configuration used: CodeRabbit UI
Files ignored due to path filters (2)
docusaurus/npm-debug.logis excluded by:!**/*.logpackage.jsonis 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 optionalfileparameter in more detail, such as when and why a developer might want to use it.Consider adding more details about the
fileparameter for theavatar([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
Friendshipclass'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.tsexample link provided in the documentation. The link responds with a "200" HTTP status code, indicating that it is accessible and valid.* 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.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
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 ofFriendshipTypevalues 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
saymethod, 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
saymethod 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
findandfindAllare 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
ContactQueryFilteris 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 returningnullin 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 thesaymethod. 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()andMessage.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
sayincludes a mix of Chinese and English, which might be confusing. Consider using either English or Chinese consistently for parameters liketext 或 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.sayand 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 parametercontactListis 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.
|
|
||
| | 名称 | 类型 | 描述 | | ||
| | :--- | :--- | :--- | | ||
| | id | `string` | 获取群ID。这个ID 是否是永久不变的ID 取决于使用哪一个puppet，具体 查看puppet兼容性清单，参照 [puppet-compatible-table](https://wechaty.js.org/docs/specs/puppet/) | |
There was a problem hiding this comment.
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 取决于使用哪一个puppetCommittable 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.
| | 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/) | |
| | 名称 | 类型 | 描述 | | ||
| | :--- | :--- | :--- | | ||
| | id | `string` | 获取联系人ID，这个ID 是否为永久唯一ID 取决于您使用什么puppet, 参照 [puppet-compatible-table](https://wechaty.js.org/docs/specs/puppet/) | |
There was a problem hiding this comment.
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取决于您使用什么puppetCommittable 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.
| | 名称 | 类型 | 描述 | | |
| | :--- | :--- | :--- | | |
| | 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/) | |
| * Wechaty | ||
| * new Wechaty\(\[options\]\) | ||
| * _实例_ | ||
| * .on\(event, listener\) ⇒ `Wechaty` | ||
| * .start\(\) ⇒ `Promise <void>` | ||
| * .stop\(\) ⇒ `Promise <void>` | ||
| * .logout\(\) ⇒ `Promise <void>` | ||
| * .logonoff\(\) ⇒ `boolean` | ||
| * .userSelf\(\) ⇒ `ContactSelf` | ||
| * .say\(textOrContactOrFileOrUrl\) ⇒ `Promise <void>` |
There was a problem hiding this comment.
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.
| The reference guide contains the technical description of the machinery. They are code determined and information oriented. The references guides contain clear descriptions of Classes, API, Functions, Methods, Attributes, and many more technical aspects of the software. The Wechaty references aim to guide the end-users completely about Wechaty. | ||
|
|
||
| ## References Index | ||
|
|
||
| 1. [API References](../api/overview.mdx) | ||
| 1. [Polyglot](../../../docs/polyglot/overview.mdx) | ||
| 1. [Puppet Providers](../../../docs/puppet-providers/overview.mdx) | ||
| 1. [Puppet Services](../../../docs/puppet-services/overview.mdx) | ||
| 1. [Specifications](../../../docs/specs/overview.mdx) |
There was a problem hiding this comment.
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
Summary by CodeRabbit
Contact,ContactSelf,Friendship,Message,Room, andWechatyitself.Wechatyclass, explaining different types of Puppets and their purposes.