API documentation should be published
rwhogg opened this issue · comments
There's JSDoc in the source code, but as far as I can tell it's not rendered and published anywhere. We should publish it - perhaps a gh-pages branch off this repo would be a good place.
Yeah, do you have any links go a good docs generator?
JSDuck is pretty nice - https://github.com/senchalabs/jsduck
+1 I'll take a look into this.. It probably will be a few weeks before I can spend time on docs.
@rwhogg I just came across this as well: http://dokkerjs.com Have you used this?
Sorry, I've never heard of it.
@rwhogg If I create a branch for gh-pages, do you want to do a pull request for this? It would be a huge help.
At this point any docs are better than no docs :).
@rwhogg I just had this idea: https://www.google.com/webhp?sourceid=chrome-instant&ion=1&espv=2&ie=UTF-8#q=jsdocs%20github%20wiki maybe we could just use jsdocs generator to generate content for the wiki! Then everything is in one site.
Sounds like a good idea, but sadly I'm really pressed for time at the moment.
@rwhogg have you had any time to look into this since June?
No. If you'd still like some help with it, I can look into it this weekend, but admittedly I haven't been doing much work with Tracekit recently.
If you could that would be a huge help
So far, I haven't had much luck with either dokker or wicked. Both keep throwing errors.
@rwhogg Thanks a ton, what are the next steps that I would need to take with jsdocs? If you could let me know what needs to be done we could steal this gh-pages logic for automatically publishing content to a gh-pages branch.
Here's what I'd recommend doing next:
- Clean up the formatting in some places. Some of the comments don't look exactly right when rendered as Markdown - particularly the comments for
TraceKit.computeStackTraceandTraceKit.report. - Document the return types for said functions with @typedef and use those type definitions rather than using inline return value descriptions.
- Pick out the functions that should be private and mark them as such.
However, these aren't strictly necessary. They'll just make the docs look nicer.
Edit: I'm currently working on trying step 2 for computeStackTrace. I'll let you know how it goes.
@rwhogg thanks a ton! Let me know when it's safe to merge or if there is anything I can do to help.
I think it looks pretty good first pass. If anything we might have to make some things @private on the inner functions.
I guess the next step is to host this someplace like on github pages?
I'm seeing the following error from grunt jsdoc after e5fbdb5 was merged:
ERROR: Unable to parse a tag's type expression for source file /home/bob/src/tracekit/tracekit.js with tag title "property" and text "{string[]=} args The arguments passed to the function, if known.": Invalid type expression "string[]=": Expected "!" or "?" but end of input found.
Warning: jsdoc terminated with a non-zero exit code Use --force to continue.
Anyhow...
Yeah, IMO the next step is to host this on GitHub Pages.
I converted it to be optional as per there spec I guess we need to change it back to ?
Sent from Outlook Mobile
On Thu, Feb 11, 2016 at 8:19 PM -0800, "Bob W. Hogg" notifications@github.com wrote:
I'm seeing the following error from grunt jsdoc after e5fbdb5 was merged:
ERROR: Unable to parse a tag's type expression for source file /home/bob/src/tracekit/tracekit.js with tag title "property" and text "{string[]=} args The arguments passed to the function, if known.": Invalid type expression "string[]=": Expected "!" or "?" but end of input found.
Warning: jsdoc terminated with a non-zero exit code Use --force to continue.
Yeah, IMO the next step is to host this on GitHub Pages.
—
Reply to this email directly or view it on GitHub.
Is there any chance you could take a stab at this. I got everything moved into GitHub actions but could use some help.
I apologize, I haven't used TraceKit in several years. I completely forgot this issue was still open; you can close it if you want.
If someone wants to submit a pr for this that would be awesome, I'm going to close this in the mean time.