Add doc #1458

lijiarui · 2018-07-10T17:50:55Z

Add js-doc for new wechaty

see wechaty/getting-started#23

The full doc can be seen: https://botorange.github.io/wechaty-doc/#/

Still, have the following functions need to be add, may need @zixia do:

Still have the following small bug due to docsify:

huan

Good job.

Please remove the changes of file docs/index.md, and follow my reviews.

huan · 2018-07-11T05:18:52Z

src/user/contact.ts

@@ -479,8 +509,12 @@ export class Contact extends Accessory implements Sayable {

  /**
   * Contact gender
+   * > Tips: ContactGender is enum here. </br>
+   * - ContactGender.Unknown = 0</br>


Please remove all numbers in the ENUM type.

ContactGender.Unknown is enough, the user should care about the number value about it, and also should never use the magic number.

huan · 2018-07-11T05:21:39Z

src/user/friendship.ts

+   * @example
+   * const bot = new Wechaty()
+   * bot.on('friendship', async friendship => {
+   *   console.log(`received friend event from ${friendship.contact().name()}`)


Please make the expression shorter, which is better for readability.

const contact = friendship.contact() const name = contact.name() console.log(`received friend event from ${name}`)

huan · 2018-07-11T05:21:59Z

src/user/friendship.ts

+  /**
+   * Return the Friendship Type
+   * > Tips: FriendshipType is enum here. </br>
+   * - FriendshipType.Unknown = 0 </br>


Get rid of all magic numbers

src/user/message.ts

+   * # 3. send Contact
+   *
+   *   if (/^lijiarui$/i.test(m.text())) {
+   *     const contactCard = await bot.Contact.find({name: 'lijiarui'})


huan · 2018-07-11T05:25:05Z

src/user/message.ts

  /**
   * Get the type from the message.
+   * > Tips: MessageType is Enum here. </br>
+   * - MessageType.Unknown   = 0, </br>


Get rid of all magic numbers.

src/user/room.ts

+   * @param {string} [text] If set this para, it will change room announce.
+   * @returns {(Promise<void | string>)}
+   *
+   * @example <caption>When you say anything in a room, it will get room announce. </caption>


huan · 2018-07-11T05:34:43Z

src/user/room.ts

-   * @deprecated use sync() instead
-   * @returns {Promise<void>}
+   * @description
+   * Force reload data for Room, use {@link Room#sync} instead


should use @ignore here.

So does sync() because they are not the public API

Why we do not make this API public?

huan · 2018-07-11T05:37:12Z

src/wechaty.ts

- * @example
- * import { Wechaty } from 'wechaty'
+ * See more:
+ * - [What is a Puppet in Wechaty](https://github.com/Chatie/wechaty-getting-started/wiki/FAQ-EN#31-what-is-a-puppet-in-wechaty)


Please do not use Wiki at wechaty-getting-started repository, we have to keep that repo as simple as possible.

I'll disable the wiki of it later, please move the FAQ to the Wiki at Wechaty Repository.

English version should be named with FAQ, and the ZH version you can name it.

huan · 2018-07-11T05:38:43Z

src/wechaty.ts

 *
+ * # 2 TypeScript


Remove the TypeScript part, because it has no typing at all, it's just ES6.

huan · 2018-07-11T05:41:20Z

src/wechaty.ts

+   * @example
+   * const bot = new Wechaty()
+   * await bot.start()
+   *


// after logged in

huan · 2018-07-11T05:45:30Z

Please put the following introduction to the doc as a start point.

Message.age()

Returns the message age in seconds.

For example, the message is sent at time 8:43:01, and when we received it in Wechaty, the time is 8:43:15, then the age() will return 8:43:15 - 8:43:01 = 14 (seconds)

Message.toFileBox()

Extract the Media File from the Message, and put it into the FileBox.

Room.qrcode()

Get QR Code of the Room from the room, which can be used as scan and join the room.

huan · 2018-07-11T09:50:11Z

Did you follow all my reviews? If not, which one had been skipped, and why?

Please leave message by replying the PR and let me know what you did in your lastest commits.

lijiarui · 2018-07-11T10:08:44Z

Yes, I follow all your reviews and change all as you request besides the following 3 things:

not totally agree with @ignore part as you said here
here you said add a link to wechaty wiki. But I have the following questions:
I agree with this suggestion but doesn't think clearly about how to add, because you just delete this and I don't know when you delete this. Then if I add something like this to the wiki, if anyone deletes this it may cause link error. But I didn't find a good solution to this.
here you said I should move wechaty-getting-started wiki to wechaty wiki, but I want to classify the wiki faq as what I did in wechaty-getting-started, and show as doc faq showed. But I don't know whether it is allowed to classify at wechaty wiki. Maybe will better, maybe will more confuse, not very sure.

huan · 2018-07-11T11:20:21Z

No, you missed some of the reviews, like remove the docs/index.md at #1458 (review)

lijiarui · 2018-07-11T11:29:19Z

Yes, you are right. I agree with you.

After we finish the 3 discussions, I will remove the docs/index.md because the latest online doc depends on this branch file.

huan · 2018-07-11T11:50:04Z

No need to discuss anymore.

Please just remove that file and I'll merge it.

lijiarui · 2018-07-12T02:48:42Z

I remove that file and you can merge it.

huan · 2018-07-12T10:58:30Z

Thank you very much for the great JSDoc!

lijiarui added 8 commits July 9, 2018 12:12

init

018e12c

add wechaty main doc

632bd33

fix wechaty comment

2652dd0

add contact doc

bb992ab

add contact more comment

c88d484

add room docs

9011c91

add message doc

77b6812

add friendship doc

fc3b971

lijiarui mentioned this pull request Jul 10, 2018

One page wechaty introduction wechaty/getting-started#23

Closed

40 tasks

huan requested changes Jul 11, 2018

View reviewed changes

lijiarui added 3 commits July 11, 2018 17:05

change as request

6ab6337

change room find function typo

57bce98

add request doc

57f7f5a

lijiarui added 3 commits July 12, 2018 10:40

Merge branch 'master' of github.com:Chatie/wechaty into add-doc

4b11580

remove index.md

2dc9a5f

removed change of docs/index

ab2cf17

lijiarui added 7 commits July 12, 2018 11:53

fix typo

c3211a0

fix message typo

eea74a5

https://github.com/qhduan/wechaty-doc/issues/19

503e691

https://github.com/qhduan/wechaty-doc/issues/20

41251fd

wechaty.init should use start instead

ca0896c

https://github.com/qhduan/wechaty-doc/issues/20

bfd3829

juzibot/wechaty-doc#20

a361b0c

lijiarui added 3 commits July 12, 2018 16:20

https://github.com/qhduan/wechaty-doc/issues/23

c84ccdc

fix contact enum things in juzibot/wechaty-doc#22

1198946

change friendship send function

f3c2b24

huan approved these changes Jul 12, 2018

View reviewed changes

huan merged commit 02d7036 into wechaty:master Jul 12, 2018

lijiarui deleted the add-doc branch July 30, 2018 15:39

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add doc #1458

Add doc #1458

lijiarui commented Jul 10, 2018 •

edited

Loading

huan left a comment

huan Jul 11, 2018

huan Jul 11, 2018

huan Jul 11, 2018

This comment was marked as resolved.

huan Jul 11, 2018

This comment was marked as resolved.

huan Jul 11, 2018

lijiarui Jul 11, 2018

huan Jul 11, 2018

huan Jul 11, 2018

huan Jul 11, 2018

huan commented Jul 11, 2018 •

edited

Loading

huan commented Jul 11, 2018

lijiarui commented Jul 11, 2018 •

edited

Loading

huan commented Jul 11, 2018 •

edited

Loading

lijiarui commented Jul 11, 2018

huan commented Jul 11, 2018

lijiarui commented Jul 12, 2018

huan commented Jul 12, 2018

Add doc #1458

Add doc #1458

Conversation

lijiarui commented Jul 10, 2018 • edited Loading

huan left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

This comment was marked as resolved.

Choose a reason for hiding this comment

This comment was marked as resolved.

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

huan commented Jul 11, 2018 • edited Loading

Message.age()

Message.toFileBox()

Room.qrcode()

huan commented Jul 11, 2018

lijiarui commented Jul 11, 2018 • edited Loading

huan commented Jul 11, 2018 • edited Loading

lijiarui commented Jul 11, 2018

huan commented Jul 11, 2018

lijiarui commented Jul 12, 2018

huan commented Jul 12, 2018

lijiarui commented Jul 10, 2018 •

edited

Loading

huan commented Jul 11, 2018 •

edited

Loading

lijiarui commented Jul 11, 2018 •

edited

Loading

huan commented Jul 11, 2018 •

edited

Loading