Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

API reference missing? #596

Open
op1ekun opened this Issue · 10 comments

10 participants

@op1ekun

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

+1

@infews
Owner

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

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

@op1ekun

@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

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

@slackersoft
Owner

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

"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

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

+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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.