API reference missing? #596

Closed
op1ekun opened this Issue May 26, 2014 · 12 comments

Comments

Projects
None yet
@op1ekun

op1ekun commented May 26, 2014

Hi guys,

I have been using Jasmine for some time, but I still don't know everything about it. There are still some things that I need to check before writing my tests. While "Introduction" page is great for understanding all the basics it's not helping if you want to find something quickly (I know how to use Ctrl + F, but it is not the best solution). I would really appreciate API reference page so I can quickly find what I'm looking for instead of going through "Introduction" page or googling it.

Thanks!

@otomi

This comment has been minimized.

Show comment Hide comment
@otomi

otomi May 29, 2014

+1

otomi commented May 29, 2014

+1

@infews

This comment has been minimized.

Show comment Hide comment
@infews

infews Jun 23, 2014

Contributor

We had API reference docs in the past. The consensus was that they were not that useful as most of Jasmine's external interface needed context to understand how it should be used. That and as the interface changed, we wanted to know if we were affecting projects.

So the benefits of the current docs are that there are examples of the entire interface and that the docs are runnable. Those pages are part of our CI build. These pages are not only higher value than our old docs, but they are dynamic enough to tell us when we've broken our community.

With three up-votes, there is something missing, but I'm not sure what is truly missing. Can you give us more examples of what you're looking for?

Contributor

infews commented Jun 23, 2014

We had API reference docs in the past. The consensus was that they were not that useful as most of Jasmine's external interface needed context to understand how it should be used. That and as the interface changed, we wanted to know if we were affecting projects.

So the benefits of the current docs are that there are examples of the entire interface and that the docs are runnable. Those pages are part of our CI build. These pages are not only higher value than our old docs, but they are dynamic enough to tell us when we've broken our community.

With three up-votes, there is something missing, but I'm not sure what is truly missing. Can you give us more examples of what you're looking for?

@jaapz

This comment has been minimized.

Show comment Hide comment
@jaapz

jaapz Jun 23, 2014

I think it's mostly that the documentation is now just a bit hard to search through.

jaapz commented Jun 23, 2014

I think it's mostly that the documentation is now just a bit hard to search through.

@op1ekun

This comment has been minimized.

Show comment Hide comment
@op1ekun

op1ekun Jun 23, 2014

@jaapz INDEED!

I'm looking for for a quick reference to ALL API methods etc. Right now I have to CTRL+F to find what I need.

I'm thinking about something like:
http://expressjs.com/4x/api.html#req.params

I want to see what's available.
That's enough for me.

op1ekun commented Jun 23, 2014

@jaapz INDEED!

I'm looking for for a quick reference to ALL API methods etc. Right now I have to CTRL+F to find what I need.

I'm thinking about something like:
http://expressjs.com/4x/api.html#req.params

I want to see what's available.
That's enough for me.

@dwelle

This comment has been minimized.

Show comment Hide comment
@dwelle

dwelle Aug 25, 2014

+1, as of now you have to skim trough code to find out the API signatures.

dwelle commented Aug 25, 2014

+1, as of now you have to skim trough code to find out the API signatures.

@slackersoft

This comment has been minimized.

Show comment Hide comment
@slackersoft

slackersoft Dec 3, 2014

Member

I think our main concern with API docs is how to keep them up-to-date, so they don't just rot. Do you have any ideas on how best to generate some kind of docs given how jasmine is set up?

Member

slackersoft commented Dec 3, 2014

I think our main concern with API docs is how to keep them up-to-date, so they don't just rot. Do you have any ideas on how best to generate some kind of docs given how jasmine is set up?

@TorstenRobitzki

This comment has been minimized.

Show comment Hide comment
@TorstenRobitzki

TorstenRobitzki Jan 2, 2015

"Jasmine has a rich set of matchers included". I was just searching the documentation for the right matcher for an empty array. As far as I get the current documentation there is no such function (toEqual([] would be the closest).

I agree with op1ekun that a reference that simply states which functions are available would be very helpful.

One approach to keep API and documentation in synch could be to have examples for every API function and to have something that executes this examples.

"Jasmine has a rich set of matchers included". I was just searching the documentation for the right matcher for an empty array. As far as I get the current documentation there is no such function (toEqual([] would be the closest).

I agree with op1ekun that a reference that simply states which functions are available would be very helpful.

One approach to keep API and documentation in synch could be to have examples for every API function and to have something that executes this examples.

@Digicrat

This comment has been minimized.

Show comment Hide comment
@Digicrat

Digicrat Mar 18, 2015

I agree that the documentation for this project could be improved (coming from a user that's evaluating this framework for the first time).

Have you considered using a library such as JSDuck or JSDoc? These work similarly to JavaDoc or Doxygen in that you use special comment syntax that combines with smart code parsing to automatically generate API documentation. Admittedly though the JS tools are not as well developed as those for other languages and may require some experimentation with explicit helper tags to get things detected the way you want.

I agree that the documentation for this project could be improved (coming from a user that's evaluating this framework for the first time).

Have you considered using a library such as JSDuck or JSDoc? These work similarly to JavaDoc or Doxygen in that you use special comment syntax that combines with smart code parsing to automatically generate API documentation. Admittedly though the JS tools are not as well developed as those for other languages and may require some experimentation with explicit helper tags to get things detected the way you want.

@maskedcoder

This comment has been minimized.

Show comment Hide comment
@maskedcoder

maskedcoder Jun 3, 2015

+1

It's very tedious to search through or skim a bunch of code. The main thing missing is a list of available functions, as mentioned by others. Even if it only linked to current examples, it would be a huge improvement. The current documentation is almost useless if I want to quickly find a function.

+1

It's very tedious to search through or skim a bunch of code. The main thing missing is a list of available functions, as mentioned by others. Even if it only linked to current examples, it would be a huge improvement. The current documentation is almost useless if I want to quickly find a function.

@qx

This comment has been minimized.

Show comment Hide comment
@qx

qx May 16, 2016

+1
Terrible experience!
eg. toExist method is not list anywhere,except stackoverflow! pleas show us api doc!

qx commented May 16, 2016

+1
Terrible experience!
eg. toExist method is not list anywhere,except stackoverflow! pleas show us api doc!

@op1ekun

This comment has been minimized.

Show comment Hide comment
@op1ekun

op1ekun May 16, 2016

@qx It's sad really...
I've switched to mocha recently mocha.
Much easier to get you head around: https://mochajs.org/#assertions

op1ekun commented May 16, 2016

@qx It's sad really...
I've switched to mocha recently mocha.
Much easier to get you head around: https://mochajs.org/#assertions

@Gerg Gerg added the docs label Sep 27, 2016

@Gerg

This comment has been minimized.

Show comment Hide comment
@Gerg

Gerg Oct 15, 2016

Contributor

@qx I agree that API-style reference documentation would be useful for Jasmine, especially for matchers. It is work noting, however, that toExist is not a core jasmine matcher: https://github.com/jasmine/jasmine/tree/master/src/core/matchers. You must be getting that matcher from another library.

Contributor

Gerg commented Oct 15, 2016

@qx I agree that API-style reference documentation would be useful for Jasmine, especially for matchers. It is work noting, however, that toExist is not a core jasmine matcher: https://github.com/jasmine/jasmine/tree/master/src/core/matchers. You must be getting that matcher from another library.

slackersoft added a commit that referenced this issue Mar 21, 2017

slackersoft added a commit that referenced this issue Mar 23, 2017

thodorisbais added a commit to thodorisbais/jasmine that referenced this issue Apr 4, 2017

thodorisbais added a commit to thodorisbais/jasmine that referenced this issue Apr 4, 2017

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