add wechaty document #725

lijiarui · 2017-08-11T10:02:16Z

huan · 2017-08-12T08:52:06Z

Thanks! Please get at least three votes(approved) from our contributor team first, because the document needs to be improved heavily and continuously.

huan

Thanks for all those hard works for the documentation, I believe it will help other developers a lot after published.

There have two additional jobs of this PR:

Please also generate the MarkDown file for the jsdoc by run npm run doc and make sure the generated document file at docs/index.md is what we want.
Please add @private to all the methods/functions which are not listed at the README API Reference section because they are just for internal use and should not be treat as published API

I also post all my reviews to the PR, please follow them as well.

huan · 2017-08-16T18:55:16Z

src/room.ts

@@ -547,9 +766,51 @@ export class Room extends EventEmitter implements Sayable {
  }

  /**
-   * @todo document me
+   * Find member by name | roomAlias(alias) | contactAlias.
+   * It got many, return the first


It -> If
return -> returns

huan · 2017-08-16T18:56:16Z

src/room.ts

+   * @returns {(Contact | null)}
+   * @example
+   * ```ts
+   * // change 'wechaty' to any room in your wechat


any room -> any room name

huan · 2017-08-16T18:56:50Z

src/room.ts

+   * @example
+   * ```ts
+   * // change 'wechaty' to any room in your wechat
+   * const room = await Room.find({topic: wechaty})


- const room = await Room.find({topic: wechaty}) + const room = await Room.find({topic: 'wechaty'})

huan · 2017-08-16T18:58:19Z

src/room.ts

+   * @example
+   * ```ts
+   * // change 'wechaty' to any room in your wechat
+   * const room = await Room.find({topic: wechaty})


huan · 2017-08-16T19:00:00Z

src/room.ts

@@ -611,7 +893,18 @@ export class Room extends EventEmitter implements Sayable {
  }

  /**
-   * @todo document me
+   * Find room by topic, return all the match room


all the matched room

huan · 2017-08-16T19:19:13Z

src/room.ts

+   * Get room leave event, emitted when bot remove someone from the room or someone remove the bot from the room.
+   * If both personA and personB are not the bot itselt, the event cannot be fired if personA remove personB from the room
+   * This is Sayable for all listeners.
+   * Which means there will be a this.say() the method inside listener call,


this.say()

huan · 2017-08-16T19:20:06Z

src/room.ts

  /**
-   * @todo document me
+   * Get room join event, emitted when someone join the room
+   * This is Sayable for all listeners.


Need not to document the this is sayable so many times.

One time is enough.

No, I think it should document on each function because not all of the developers will read the whole doc.

So do you mean that if something is important, then we should put it everywhere?

I have to disagree with you.

huan · 2017-08-16T19:21:33Z

src/room.ts

  /**
-   * @todo document me
+   * Get EVENT_PARAM_ERROR event


The EVENT_PARAM_ERROR is just a guard for IDE Intelligence.

Need not be documented, and should be set to @private

huan · 2017-08-16T19:22:13Z

src/room.ts

  /**
-   * @todo document me
+   * Get RoomEventName event


This method is the implementation of all the event listeners above.

No need to be documented too.

huan · 2017-08-16T19:22:41Z

src/room.ts

+   * @example
+   * ```ts
+   * const room = await Room.find({name: 'wechaty'}) // change 'wechaty' to any of your room in wechat
+   * await room.say('/test.jpg') // put the filePath you want to send here


await room.say(new MediaMessage('/test.jpg'))

lijiarui · 2017-08-17T19:12:55Z

here is the auto generate doc: https://github.com/lijiarui/wechaty/blob/new-doc/docs/index.md

not sure why it has double wechaty intro....

will keep on dig in it, or anyone can help? @ax4

kis87988 · 2017-08-18T00:32:09Z

src/message.ts

+ *
+ * Enum for MsgType values.
+ * @enum {number}
+ */


we should include message type in to documentation
update: I saw you write below. then should we just private this in documentation?

How about the latest one?
https://github.com/lijiarui/wechaty/blob/master/docs/index.md#msgtype--enum

it looks nice:)

kis87988 · 2017-08-18T00:57:03Z

maybe we should add all return promise type with notice "await"

huan · 2017-08-18T02:15:18Z

In our current implementation of the doc generator script npm run doc, when we are generating the document, it is actually reading the jsdoc from dist/**/*.js, like dist/src/wechaty.js. You can generate the files under dist/ directory by run npm run dist, and make sure all the javascript class with jsdoc looks good.

BTW: I saw lots of ISC License in the generated document, it's not right. The license of the Wechaty project is Apache-2.0. There might have some comments say "ISC license", should be replaced.

kis87988 · 2017-08-18T03:19:39Z

ISC License should be changed in whchaty.ts @line #68

huan · 2017-08-18T04:02:32Z

Thanks, @kis87988, I had fixed that by removing the LICENSE info.

coveralls · 2017-08-18T06:50:52Z

Coverage remained the same at 54.688% when pulling 5a7802b on lijiarui:master into d3aa251 on Chatie:master.

huan

Thanks for the update, it looks better now.

Could you please include the docs/index.md in the next PR?

Please make sure that the index.md file content is expected.

Have a nice weekend!

huan · 2017-08-18T07:42:54Z

src/contact.ts

@@ -651,6 +679,9 @@ export class Contact implements Sayable {
                  })
  }

+  /**
+   * @deprecated


also @private for @deprecated, please.

huan · 2017-08-18T10:11:51Z

src/message.ts

+   * Set the destination as Contact for the message
+   *
+   * @param {Contact} contact
+   * @returns {void}
   */
  public to(contact: Contact): void


This method should be marked as @private because normally use should not use Wechaty API to set the destination of the message by call to().

We use Sayables to send message to contact, like contact.say() and room.say()

huan · 2017-08-18T10:12:26Z

src/message.ts

+  /**
+   * Set the destination as Contact by 'weixinID', eg: 'filehelper', for the message
+   *
+   * @param {string} id


should be marked as @private

huan · 2017-08-18T10:12:48Z

src/message.ts

+  /**
+   * Set the destination as Contact by 'weixinID', eg: 'filehelper', for the message
+   *
+   * @param {string} id


should be marked as @private

huan · 2017-08-18T10:13:25Z

src/message.ts

+   * Set the room for a message
+   *
+   * @param {Room} room
+   * @returns {void}
   */
  public room(room: Room): void


Should be marked as @private

huan · 2017-08-18T10:17:04Z

src/message.ts

@@ -667,12 +858,34 @@ export class Message implements Sayable {
 // Message.initType()

 export class MediaMessage extends Message {
+  /**
+   * @private


I think if the class property is already private, then we will not need to use @private in jsdoc again?

huan · 2017-08-18T10:18:58Z

src/message.ts

+   *
+   * @returns {string}
+   * @example
+   * ```ts


Could you please help me to find a button with resolve text on it, near this review message?

Because @binsee also need that button... thanks.

huan · 2017-08-18T10:26:16Z

src/message.ts

+   *
+   * @returns {string}
+   * @example
+   * ```ts


please mark the review as resolved by GitHub button.

huan · 2017-08-18T10:36:35Z

src/room.ts

@@ -440,7 +667,9 @@ export class Room extends EventEmitter implements Sayable {
  }

  /**
-   * @todo document me
+   * Get room's owner from the room.
+   * Not recommend, because cannot always get the owner


please add @deprecated because it is very useless, almost no use.

huan · 2017-08-18T10:42:48Z

src/wechaty.ts

+   *   const nameList = leaverList.map(c => c.name()).join(',')
+   *   console.log(`Room ${room.topic()} lost member ${nameList}`)
+   * })
+   * ```
   */
  public on(event: 'room-leave' , listener: (this: Wechaty, room: Room, leaverList: Contact[]) => void): this


Please add a notice about the silent leave:

If someone leaves the room by themselves, wechat will not notice other people in the room, so the bot will never get the "leave" event.

huan

There are too many unrelated changes in the diff.

Please only keep the related change in PR.

huan · 2017-08-21T05:44:21Z

docs/index.md

+if (ret) {
+  console.log(`change ${contact.name()}'s alias successfully!`)
+} else {
+  console.error('failed to change ${contact.name()}'s alias!')


- console.error('failed to change ${contact.name()}'s alias!') + console.error(`failed to change ${contact.name()}`s alias!')

huan · 2017-08-21T05:46:29Z

src/contact.ts

@@ -1,7 +1,8 @@
 /**
+ *   @ignore


Could we move @ignore to the end of the comment, instead of at the beginning of?

huan · 2017-08-21T05:50:35Z

src/message.ts

-  public typeApp(): AppMsgType {
-    if (!this.rawObj) {
-      throw new Error('no rawObj')
+  public say(textOrMedia: string | MediaMessage, replyTo?: Contact|Contact[]): Promise<any> {


Why did you rewrite so many original methods, could you get rid of all the unrelated changes?

Because it makes the diff shows lots of mess, and make the review becomes a hard job.

huan · 2017-08-21T05:52:56Z

src/message.ts

+   * @see {@link MsgType}
+   * @returns {MsgType}
+   */
+  public type(): MsgType {


The same question as above: your diff should not include unrelated changes.

huan

The jsdoc looks better to me now, thank you very much for all the work of writing the documents and examples!

I have some minor reviews. After resolved them, I'll be able to vote for my approvement.

huan · 2017-08-21T09:23:27Z

docs/index.md

+if (ret) {
+  console.log(`change ${contact.name()}'s alias successfully!`)
+} else {
+  console.error('failed to change ${contact.name()}'s alias!')


huan · 2017-08-21T09:24:49Z

src/contact.ts

   * @example
-   * ```ts


Could please confirm it for me that we do not need "```ts" block inside @example?

yes, I looked into the doc and confirmed, then changed all ``` inside @example

see http://usejsdoc.org/tags-example.html

Great, thanks.

huan · 2017-08-21T09:28:03Z

src/contact.ts

@@ -277,52 +278,40 @@ export class Contact implements Sayable {
  /**
   * Contact gender
   *
-   * @returns Gender.Male(2) | Gender.Female(1) | Gender.Unknown(0)


Just use Gender.Male Gender.Female and Gender.Unknown, there's no need to refer the number value of them because that's why ENUM type exists: Do not rely on the magic numbers.

So does the other ENUM types.

well, m.type() return too much type, are you sure use like this?

https://github.com/lijiarui/wechaty/blob/master/docs/index.md#Message+type

Yes. Just use the ENUM names please.

huan · 2017-08-21T09:29:05Z

src/contact.ts

+   * The way to search Contact
+   *
+   * @typedef    ContactQueryFilter
+   * @property   {string} name    -the name-string set by user-self, should be called name


-the name to - The name?

huan · 2017-08-21T09:33:19Z

src/contact.ts

   */
-  public async say(text: string)


Why you deleted the overloading function declaration?

They should be kept because those are for TypeScript IDE Intelligence.

huan · 2017-08-21T09:35:11Z

src/message.ts

+ * Enum for AppMsgType values.
+ *
+ * @enum {number}
+ * @property {number} TEXT                    - 1      for TEXT


We should just let users know AppMsgType.IMG, without the exact number.

When we use Wechaty, we should just use AppMsgType.IMG instead of 2

do you mean change 1 to AppMsgType .TEXT here?

I think so if there's no other problem.

After I thought more if any want to know the number for more development, such as ipad protocol or xposed, maybe we should tell them the wechat raw number, So I add both AppMsgType .TEXT and 1 here.

I'll not argue with you about that, It's ok.

But I'd like to assume that the other protocols are different with the Web.

huan · 2017-08-21T09:36:33Z

src/message.ts

   */
-  public content(): string


Please keep the overloading method declaration.

huan · 2017-08-21T09:38:47Z

src/room.ts

-   * @todo document me
+   * @desc       Room Class Event Function
+   * @typedef    RoomEventFunction
+   * @property   {Function} room-join       -(this: Room, inviteeList: Contact[] , inviter: Contact)  => void


Add a space? - (this...

hczhcz

Great job! The documentation looks good to me.

There might be something need to be modified, but I would suggest merge this PR and do these updates in successor PRs.

hczhcz · 2017-08-30T16:05:03Z

src/contact.ts

 *   Wechaty - https://github.com/chatie/wechaty
 *
- *   Copyright 2016-2017 Huan LI <zixia@zixia.net>
+ *   @copyright 2016-2017 Huan LI <zixia@zixia.net>


It would be better if all files share the same header (copyright info, license, etc)

@hczhcz thanks! I'll do that later by an util script written by me at https://github.com/Chatie/wechaty/blob/master/script/update-license.ts, in case you are interested at.

binsee · 2017-08-31T10:19:04Z

look forward to merge

lijiarui · 2017-08-31T11:59:31Z

@binsee Could you help to approve this pull request? then @zixia can merge this, thanks!

binsee

good job

huan · 2017-08-31T14:22:07Z

Great! Thank you @hczhcz @binsee for reviewing this PR, appreciate that!

…om/Chatie/wechaty/pull/725/files#r136114369 (#725)

add doc

a3e2be7

huan requested review from JasLin, dcsan, xinbenlv, a user, Gcaufy, imWildCat, hailiang-wang and TingYinHelen August 12, 2017 08:48

remove useless doc

b374641

huan requested changes Aug 16, 2017

View reviewed changes

huan removed the request for review from imWildCat August 16, 2017 19:39

lijiarui added 2 commits August 18, 2017 02:47

change as request

4461884

remove private

b9b348e

kis87988 reviewed Aug 18, 2017

View reviewed changes

huan requested review from hczhcz and mukaiu August 18, 2017 02:16

Merge branch 'master' of github.com:Chatie/wechaty

5a7802b

lijiarui requested a review from huan August 18, 2017 06:31

huan requested changes Aug 18, 2017

View reviewed changes

lijiarui added 2 commits August 21, 2017 04:17

add doc

8f39785

add docs index

34933c6

lijiarui added 3 commits August 21, 2017 04:19

add todo & desprate

67beba8

Merge branch 'master' of github.com:Chatie/wechaty

bbc6da6

change function order

4fcebef

lijiarui requested a review from huan August 20, 2017 20:40

lijiarui added 3 commits August 21, 2017 10:36

add \n

5b99da7

code clean

3e84d82

code clean

060f10f

huan requested changes Aug 21, 2017

View reviewed changes

lijiarui added 3 commits August 21, 2017 15:06

recover contact order

59bcd73

recover order

1b59140

change ignore & `

07b009c

lijiarui requested a review from huan August 21, 2017 07:42

huan requested changes Aug 21, 2017

View reviewed changes

lijiarui added 4 commits August 21, 2017 19:43

change as request

a9cdae0

change Gender

150b3ff

Merge branch 'master' of github.com:Chatie/wechaty

f3d03f7

add overloading method declaration & change mstType

6722b3d

lijiarui requested a review from huan August 27, 2017 11:47

huan approved these changes Aug 27, 2017

View reviewed changes

huan mentioned this pull request Aug 30, 2017

William doc dev #701

Closed

hczhcz approved these changes Aug 30, 2017

View reviewed changes

lijiarui requested a review from binsee August 31, 2017 11:59

binsee approved these changes Aug 31, 2017

View reviewed changes

huan merged commit da8c652 into wechaty:master Aug 31, 2017

huan added a commit that referenced this pull request Aug 31, 2017

update(license): use @copyright instead of Copyright https://github.c…

0971a3b

…om/Chatie/wechaty/pull/725/files#r136114369 (#725)

huan added a commit that referenced this pull request Aug 31, 2017

update(license): use @copyright instead of Copyright https://github.c…

e9e12d7

…om/Chatie/wechaty/pull/725/files#r136114369 (#725)

add wechaty document #725

add wechaty document #725

Conversation

lijiarui commented Aug 11, 2017

huan commented Aug 12, 2017

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

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

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

lijiarui commented Aug 17, 2017 • edited Loading

kis87988 Aug 18, 2017 • edited Loading

Choose a reason for hiding this comment

lijiarui Aug 21, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kis87988 commented Aug 18, 2017

huan commented Aug 18, 2017 • edited Loading

kis87988 commented Aug 18, 2017

huan commented Aug 18, 2017

coveralls commented Aug 18, 2017 • 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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

huan Aug 18, 2017 • edited Loading

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 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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

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

lijiarui Aug 21, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lijiarui Aug 21, 2017 • edited Loading

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

Choose a reason for hiding this comment

huan Aug 21, 2017 • edited Loading

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

hczhcz left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

binsee commented Aug 31, 2017

lijiarui commented Aug 31, 2017

binsee left a comment

Choose a reason for hiding this comment

lijiarui commented Aug 17, 2017 •

edited

Loading

kis87988 Aug 18, 2017 •

edited

Loading

lijiarui Aug 21, 2017 •

edited

Loading

huan commented Aug 18, 2017 •

edited

Loading

coveralls commented Aug 18, 2017 •

edited

Loading

huan Aug 18, 2017 •

edited

Loading

lijiarui Aug 21, 2017 •

edited

Loading

lijiarui Aug 21, 2017 •

edited

Loading

huan Aug 21, 2017 •

edited

Loading

hczhcz left a comment •

edited

Loading

huan commented Aug 31, 2017 •

edited

Loading