Skip to content
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.

Sign up for GitHub

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

Jump to bottom

jsdoc2md may flush some pieces of the embedded doc #378

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

jsdoc2md may flush some pieces of the embedded doc #378

ax4 opened this issue Mar 30, 2017 · 3 comments

Comments

@ax4
Copy link
Member

ax4 commented Mar 30, 2017 •
edited
Loading

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
    https://github.com/Chatie/wechaty/blob/b77c241d7d716635c5481ed734b32e303fce8e4c/src/contact.ts#L430-L505
  2. The compiled JS missing "that piece"
    flush_cause
  3. Cause the missing in the final doc
    flush_result
@ax4
Copy link
Member Author

ax4 commented Mar 30, 2017 •
edited
Loading

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)

~~~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 https://github.com/Chatie/wechaty/blob/b77c241d7d716635c5481ed734b32e303fce8e4c/src/contact.ts#L480-L505

I will soon fix this piece of doc, using the [optional parameter by jsdoc](http://usejsdoc.org/tags-param.html#optional-parameters-and-default-values) and the [multiple-types by jsdoc](http://usejsdoc.org/tags-param.html#multiple-types-and-repeatable-parameters)

@huan
Copy link
Member

huan commented Mar 30, 2017

Glad to see you start working on this! 👍

@ax4 ax4 mentioned this issue Mar 31, 2017
Merged
huan pushed a commit that referenced this issue Mar 31, 2017
@huan
fix jsdoc flush issue #378 and minor fix on the doc examples (#380)
ba18316 
* 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.
@huan
Copy link
Member

huan commented May 9, 2017

Merge to #252

@huan huan closed this as completed May 9, 2017
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@huan @ax4