search

jamesshore / quixote

CSS unit and integration testing
Other
847 stars 45 forks source link

Activate IDE Intellisense for Quixote symbols #22

Closed woldie closed 7 years ago

woldie commented 8 years ago

UPDATE: This issue originally had too broad a scope, covering using JSDoc for both Intellisense and for Markdown document generation. Going forward, this issue will focus on IDE Intellisense and a separate issue will be opened for Markdown document generation.

Having Quixote ship with JSDoc annotations in the codebase will enable IDE's like IntelliJ or WebStorm to provide suggestions to users when they access fields and functions in the Quixote library.

jamesshore commented 8 years ago

I think there's two separate issues here:

1) Using JSDoc to auto-generate documentation 2) Using JSDoc for IDE intellisense

I'm in agreement about using JSDoc for IDEs and will happily accept a pull request that adds it.

I'm not so sure that JSDoc will do a good job of generating documentation. I'd rather have HTML docs than the Markdown docs we have now, so that's not the problem. I have two concerns about auto-generating the docs:

1) Our current documents are very thorough and I worry that putting that level of detail directly in the code will make it hard to read.

2) The descriptor docs don't follow a standard format and seem like they wouldn't autogenerate well.

It might be a good idea to open a separate issue for the question of auto-generating the docs.

woldie commented 8 years ago

I believe your concerns about generating markdown documentation from JSDoc are shared by others in the jsdoc2markdown community. I've seen a lot of conversations in their issue log where users need to somehow stitch together external markdown files that contain extensive texts rather than trying to shoehorn all that into the JSDoc comments. That sounds awkward, and I agree we should avoid that.

I don't think it makes sense to try to reproduce your existing documentation fully with jsdoc2markdown. But, if the API markdown that only covers the class and method signatures could be separated from the cookbook/getting started docs, then I think it would make a lot more sense.

I'll split off this issue of "documentation generation via JSDoc" from "JSDoc for Intellisense" which you and I agree has more utility in the near-term.

jamesshore commented 8 years ago

See #23 for "autogenerate documentation" issue.

jamesshore commented 8 years ago

It seems that Typescript can also be used to enable Intellisense, and there's already a desire for that. (See #16.) I'm going to change the title to be implementation-agnostic.

jamesshore commented 7 years ago

Closing this issue due to lack of activity.