New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

jsdoc2md may flush some pieces of the embedded doc #378

Closed
ax4 opened this Issue Mar 30, 2017 · 3 comments

Comments

Projects
None yet
2 participants
@ax4
Member

ax4 commented Mar 30, 2017

In brief, this issue is caused by our auto-doc working flow, at the 1st step npm run dist (compile TS into JS), it flushes some pieces of embedded doc May Impact #252 #73

Our auto-doc working flow (with jsdoc / jsdoc2md):

1. dev in TS
2. embedded doc insert in TS
3. compile TS into JS (#warning# this step cause flush)
4. run jsdoc / jsdoc2md
5. get the final doc

See more in details:

  1. A piece of embedded doc in TS

    wechaty/src/contact.ts

    Lines 430 to 505 in b77c241

    /**
    * Get the alias for contact
    *
    * @returns {(string | null)}
    *
    * @example
    * ```ts
    * const alias = contact.alias()
    * ```
    */
    public alias(): string | null
    /**
    * set the alias for contact
    *
    * tests show it will failed if set alias too frequently(60 times in one minute).
    *
    * @param {string} newAlias
    * @returns {Promise<boolean>} A promise to the result. true for success, false for failure
    *
    * @example
    * ```ts
    * const ret = await contact.remark('lijiarui')
    * if (ret) {
    * console.log(`change ${contact.name()}'s alias successfully!`)
    * } else {
    * console.error('failed to change ${contact.name()}'s alias!')
    * }
    * ```
    */
    public alias(newAlias: string): Promise<boolean>
    /**
    * Delete the alias for a contact
    *
    * @param {null} empty
    * @returns {Promise<boolean>}
    *
    * @example
    * ```ts
    * const ret = await contact.remark(null)
    * if (ret) {
    * console.log('ok!')
    * } else {
    * console.error('fail!')
    * }
    * ```
    */
    public alias(empty: null): Promise<boolean>
    public alias(newAlias?: string|null): Promise<boolean> | string | null {
    log.silly('Contact', 'alias(%s)', newAlias || '')
    if (newAlias === undefined) {
    return this.obj && this.obj.alias || null
    }
    return Config.puppetInstance()
    .contactAlias(this, newAlias)
    .then(ret => {
    if (ret) {
    if (this.obj) {
    this.obj.alias = newAlias
    } else {
    log.error('Contact', 'alias() without this.obj?')
    }
    } else {
    log.warn('Contact', 'alias(%s) fail', newAlias)
    }
    return ret
    })
    .catch(e => {
    log.error('Contact', 'alias(%s) rejected: %s', newAlias, e.message)
    return false // fail safe
    })
    }
  2. The compiled JS missing "that piece"
    flush_cause
  3. Cause the missing in the final doc
    flush_result
@ax4

This comment has been minimized.

Show comment
Hide comment
@ax4

ax4 Mar 30, 2017

Member

I will look deeper into this problem, and trying to solve it, within 24 hours!

Possible solution: (I haven't tried, I will do it)
1. Give up the 'one-to-one edit strategy' like this, try to put only one piece for the same name function, and see if this can avoid flush?
2. Use TypeDoc, it generate good & informative doc, directly from TS files
3. Manually apply the missing piece onto JS files (need human / bot to do the job)

Update:

Ok I figure out how this piece of embedded doc got flushed.

It was because missing document on this part

wechaty/src/contact.ts

Lines 480 to 505 in b77c241

public alias(newAlias?: string|null): Promise<boolean> | string | null {
log.silly('Contact', 'alias(%s)', newAlias || '')
if (newAlias === undefined) {
return this.obj && this.obj.alias || null
}
return Config.puppetInstance()
.contactAlias(this, newAlias)
.then(ret => {
if (ret) {
if (this.obj) {
this.obj.alias = newAlias
} else {
log.error('Contact', 'alias() without this.obj?')
}
} else {
log.warn('Contact', 'alias(%s) fail', newAlias)
}
return ret
})
.catch(e => {
log.error('Contact', 'alias(%s) rejected: %s', newAlias, e.message)
return false // fail safe
})
}

I will soon fix this piece of doc, using the optional parameter by jsdoc and the multiple-types by jsdoc

Member

ax4 commented Mar 30, 2017

I will look deeper into this problem, and trying to solve it, within 24 hours!

Possible solution: (I haven't tried, I will do it)
1. Give up the 'one-to-one edit strategy' like this, try to put only one piece for the same name function, and see if this can avoid flush?
2. Use TypeDoc, it generate good & informative doc, directly from TS files
3. Manually apply the missing piece onto JS files (need human / bot to do the job)

Update:

Ok I figure out how this piece of embedded doc got flushed.

It was because missing document on this part

wechaty/src/contact.ts

Lines 480 to 505 in b77c241

public alias(newAlias?: string|null): Promise<boolean> | string | null {
log.silly('Contact', 'alias(%s)', newAlias || '')
if (newAlias === undefined) {
return this.obj && this.obj.alias || null
}
return Config.puppetInstance()
.contactAlias(this, newAlias)
.then(ret => {
if (ret) {
if (this.obj) {
this.obj.alias = newAlias
} else {
log.error('Contact', 'alias() without this.obj?')
}
} else {
log.warn('Contact', 'alias(%s) fail', newAlias)
}
return ret
})
.catch(e => {
log.error('Contact', 'alias(%s) rejected: %s', newAlias, e.message)
return false // fail safe
})
}

I will soon fix this piece of doc, using the optional parameter by jsdoc and the multiple-types by jsdoc

@zixia

This comment has been minimized.

Show comment
Hide comment
@zixia

zixia Mar 30, 2017

Member

Glad to see you start working on this! 👍

Member

zixia commented Mar 30, 2017

Glad to see you start working on this! 👍

zixia added a commit that referenced this issue Mar 31, 2017

fix jsdoc flush issue #378 and minor fix on the doc examples (#380)
* fix Upcase

* use .alias() instead of .remark() 

contact.remark() should be deprecated

* fix Upcase

* use .alias() instead of .remark() 

contact.remark() should be deprecated

* fix the embeded doc for .alias()

* fix trailing whitespace

* Limit the size of the sending file (#376)

* Limit the size of the sending file

* limit vedio size

* add remark

* tslint

* Optimize videoMaxSize limit

* tslint

* fix Upcase

* use .alias() instead of .remark() 

contact.remark() should be deprecated

* fix the embeded doc for .alias()

* fix trailing whitespace

* remove  unnecessary comments in the exmaple code

* better example code

* Set / Get / Delete => SET / GET /DELETE

* better delete alias example

* Revert "Limit the size of the sending file (#376)"

This reverts commit a59984e.
@zixia

This comment has been minimized.

Show comment
Hide comment
@zixia

zixia May 9, 2017

Member

Merge to #252

Member

zixia commented May 9, 2017

Merge to #252

@zixia zixia closed this May 9, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment