📝Write doc for friendship module (#352)

Author: seng1e

docs/references/friendship.md

@@ -2,38 +2,23 @@
 title: Friendship
 ---
 
-发送、接收好友请求和好友确认事件。
+# class Friendship()
+> 发送、接收好友请求和好友确认事件。
+> [示例/Friend-Bot](https://github.com/wechaty/python-wechaty-getting-started/blob/master/examples/advanced/friendship-bot.py)
 
-## Friendship
 
-发送、接收好友请求和好友确认事件。
+::: wechaty.user.friendship.Friendship.search
 
-1. 发送请求
-2. 接收请求\(in friend event\)
-3. 接受请求\(friend event\)
-
-[示例/Friend-Bot](https://github.com/wechaty/python-wechaty-getting-started/blob/master/examples/advanced/friendship-bot.py)
-
-**类型**: 全局类
-
-* [Friendship](friendship.md#Friendship)
-  * _实例方法_
-    * [.accept\(\)](friendship.md#Friendship+accept) ⇒ `None`
-    * [.hello\(\)](friendship.md#Friendship+hello) ⇒ `str`
-    * [.contact\(\)](friendship.md#Friendship+contact) ⇒ `Contact`
-    * [.type\(\)](friendship.md#Friendship+type) ⇒ `FriendshipType`
-  * _静态方法_
-    * [~~.send\(\)~~](friendship.md#Friendship.send)
-    * [.add\(contact, hello\)](friendship.md#Friendship.add) ⇒ `None`
-
-### friendship.accept\(\) ⇒ `None`
-
-接受朋友请求
-
-**类型**: [`Friendship`](friendship.md#Friendship)的实例方法  
-
-#### 示例
+::: wechaty.user.friendship.Friendship.add
+### 示例代码
+```python
+memberList = await room.memberList()
+for member in memberList:
+    await bot.Friendship.add(member, 'Nice to meet you! I am wechaty bot!')
+```
 
+::: wechaty.user.friendship.Friendship.contact
+### 示例代码
 ```python
 import asyncio
 from wechaty import Wechaty, Friendship
@@ -44,97 +29,45 @@ class MyBot(Wechaty):
     async on_friendship(self, friendship: Friendship) -> None:
         contact = friendship.contact()
         await contact.ready()
-
-        if friendship.type() == FriendshipType.FRIENDSHIP_TYPE_RECEIVE:
-            log_msg = 'accepted automatically'
-            await friendship.accept()
-            # if want to send msg, you need to delay sometimes
-
-            print('waiting to send message ...')
-            await asyncio.sleep(3)
-            await contact.say('hello from wechaty ...')
-            print('after accept ...')
-        elif friendship.type() == FriendshipType.FRIENDSHIP_TYPE_CONFIRM:
-            log_msg = 'friend ship confirmed with ' + contact.name
-
+        log_msg = f'receive "friendship" message from {contact.name}'
         print(log_msg)
 
+
 asyncio.run(MyBot().start())
 ```
 
-### friendship.hello\(\) ⇒ `str`
-
-Get verify message from
-
-**类型**: [`Friendship`](friendship.md#Friendship)的实例方法  
-
-**示例** 
-
-_\(If request content is \`ding\`, then accept the friendship\)_
-
+::: wechaty.user.friendship.Friendship.accept
+### 示例代码
 ```python
 import asyncio
 from wechaty import Wechaty, Friendship
 
-
 class MyBot(Wechaty):
 
     async on_friendship(self, friendship: Friendship) -> None:
         contact = friendship.contact()
         await contact.ready()
 
-        if friendship.type() == FriendshipType.FRIENDSHIP_TYPE_RECEIVE and friendship.hello() == 'ding':
-            log_msg = 'accepted automatically because verify messsage is "ding"'
+        if friendship.type() == FriendshipType.FRIENDSHIP_TYPE_RECEIVE:
+            log_msg = 'accepted automatically'
             await friendship.accept()
             # if want to send msg, you need to delay sometimes
 
             print('waiting to send message ...')
             await asyncio.sleep(3)
             await contact.say('hello from wechaty ...')
             print('after accept ...')
+        elif friendship.type() == FriendshipType.FRIENDSHIP_TYPE_CONFIRM:
+            log_msg = 'friend ship confirmed with ' + contact.name
 
-asyncio.run(MyBot().start())
-```
-
-### friendship.contact\(\) ⇒ `Contact`
-
-获取邀请的联系人对象
-
-**类型**: [`Friendship`](friendship.md#Friendship)的实例方法  
-
-#### 示例
-
-```python
-import asyncio
-from wechaty import Wechaty, Friendship
-
-
-class MyBot(Wechaty):
-
-    async on_friendship(self, friendship: Friendship) -> None:
-        contact = friendship.contact()
-        await contact.ready()
-        log_msg = f'receive "friendship" message from {contact.name}'
         print(log_msg)
 
-
 asyncio.run(MyBot().start())
 ```
 
-### friendship.type\(\) ⇒ `FriendshipType`
-
-返回Friendship请求的类型
-
-> 提示: FriendshipType在这里是枚举类型. </br>
->
-> * FriendshipType.FriendshipTypeFRIENDSHIP_TYPE_UNSPECIFIED
-> * FriendshipType.FRIENDSHIP_TYPE_CONFIRM 
-> * FriendshipType.FRIENDSHIP_TYPE_RECEIVE 
-> * FriendshipType.FRIENDSHIP_TYPE_VERIFY 
-
-**类型**: [`Friendship`](friendship.md#Friendship)的实例方法  
-
-**示例** _\(If request content is \`ding\`, then accept the friendship\)_
+::: wechaty.user.friendship.Friendship.hello
+### 示例代码
+> 自动接受好友请求中包含消息为 `ding` 的好友请求
 
 ```python
 import asyncio
@@ -160,32 +93,6 @@ class MyBot(Wechaty):
 asyncio.run(MyBot().start())
 ```
 
-### ~~Friendship.send\(\)~~
-
-_**已弃用**_
-
-请使用[Friendship\#add](friendship.md#friendship-add-contact-hello-promise)
-
-**类型**:  [`Friendship`](friendship.md#Friendship)的静态方法
-
-### Friendship.add\(contact, hello\) ⇒ `Promise <void>`
-
-Send a Friend Request to a `contact` with message `hello`.
-
-The best practice is to send friend request once per minute. Remeber not to do this too frequently, or your account may be blocked.
+::: wechaty.user.friendship.Friendship.type
 
-**类型**:  [`Friendship`](friendship.md#Friendship)的静态方法
-
-| 参数 | 类型 | 描述 |
-| :--- | :--- | :--- |
-| contact | `Contact` | Send friend request to contact |
-| hello | `string` | The friend request content |
-
-#### Example
-
-```python
-memberList = await room.memberList()
-for member in memberList:
-    await bot.Friendship.add(member, 'Nice to meet you! I am wechaty bot!')
-
-```
+::: wechaty.user.friendship.Friendship.from_json

src/wechaty/user/friendship.py

@@ -69,8 +69,10 @@ def __init__(self, friendship_id: str):
     def load(cls, friendship_id: str) -> Friendship:
         """
         load friendship without payload, which loads in a lazy way
-        :param friendship_id:
-        :return: initialized friendship
+        Args:
+            friendship_id: the id of the friendship
+        Returns:
+            Friendship: initialized friendship
         """
         return cls(friendship_id)
 
@@ -79,10 +81,18 @@ async def search(cls, weixin: Optional[str] = None,
                      phone: Optional[str] = None) -> Optional[Contact]:
         """
         * Search a Friend by phone or weixin.
-        *
-        * The best practice is to search friend request once per minute.
-        * Remeber not to do this too frequently, or your account
-        * may be blocked.
+        * The best practice is to search friend request once per minute.\
+            Remeber not to do this too frequently, or your account \
+            will be blocked.
+
+        Args:
+            weixin: the weixin id of the contact
+            phone: the phone of the contact
+        Examples:
+            >>> friendship = await Friendship.search('phone')
+            >>> friendship.contact()
+        Returns:
+            Contact: the contact found
         """
         log.info('search() <%s, %s, %s>', cls, weixin, phone)
         friend_id = await cls.get_puppet().friendship_search(weixin=weixin,
@@ -97,6 +107,15 @@ async def search(cls, weixin: Optional[str] = None,
     async def add(cls, contact: Contact, hello: str) -> None:
         """
         add friendship
+
+        Args:
+            contact: the contact to be added
+            hello: the hello message
+        Examples:
+            >>> contact = Contact.load('contact_id')
+            >>> await Friendship.add(contact, 'hello')
+        Returns:
+            None
         """
         log.info('add() <%s, %s>', contact.contact_id, hello)
         await cls.get_puppet().friendship_add(
@@ -135,14 +154,25 @@ async def ready(self, force_sync: bool = False) -> None:
     def contact(self) -> Contact:
         """
         get the contact of the friendship
+        Args:
+            None
+        Examples:
+            >>> contact = friendship.contact()
+        Returns:
+            Contact: the contact of the friendship
         """
-
         contact = self.wechaty.Contact.load(self.payload.contact_id)
         return contact
 
     async def accept(self) -> None:
         """
         accept friendship
+        Args:
+            None
+        Examples:
+            >>> await friendship.accept()
+        Returns:
+            None
         """
         log.info('accept friendship, friendship_id: <%s>', self.friendship_id)
         if self.type() != FriendshipType.FRIENDSHIP_TYPE_RECEIVE:
@@ -167,8 +197,13 @@ async def accept(self) -> None:
 
     def hello(self) -> str:
         """
-        TODO ->
-        Get verify message from
+        Get verify message from received friendship request
+        Args:
+            None
+        Examples:
+            >>> hello_msg = friendship.hello()
+        Returns:
+            str: the hello message
         """
         if self.payload.hello is None:
             hello_msg = ''
@@ -182,6 +217,19 @@ def hello(self) -> str:
     def type(self) -> FriendshipType:
         """
         Return the Friendship Type
+        Note:
+            `FriendshipType` is an enumeration type
+
+             * FriendshipType.FriendshipTypeFRIENDSHIP_TYPE_UNSPECIFIED
+             * FriendshipType.FRIENDSHIP_TYPE_CONFIRM
+             * FriendshipType.FRIENDSHIP_TYPE_RECEIVE
+             * FriendshipType.FRIENDSHIP_TYPE_VERIFY
+        Args:
+            None
+        Examples:
+            >>> friendship.type()
+        Returns:
+            FriendshipType: the type of the friendship
         """
         if self.payload is None:
             return FriendshipType.FRIENDSHIP_TYPE_UNSPECIFIED
@@ -207,6 +255,12 @@ async def from_json(
     ) -> Friendship:
         """
         create friendShip by friendshipJson
+        Args:
+            json_data: the json data of the friendship
+        Examples:
+            >>> friendship = Friendship.from_json(friendshipJson)
+        Returns:
+            Friendship: the friendship created
         """
         log.info('from_json() <%s>', json_data)
         if isinstance(json_data, str):