Skip to content

Add documentation about how it works #9

Closed
kossnocorp opened this Issue Dec 2, 2012 · 8 comments

3 participants

@kossnocorp
Owner

No description provided.

@rstacruz
Collaborator

What sort of documentation did you have in mind?

@ericf
ericf commented Feb 26, 2013

@kossnocorp the thing is a few lines of code https://github.com/kossnocorp/jquery.turbolinks/blob/master/src/jquery.turbolinks.coffee

There's so much project ceremony for such little code.

@kossnocorp
Owner

@ericf not every person read code what he uses (I wish but it's cruel reality) and jQuery Turbolinks has very tricky behaviour. So I think is good idea to have detailed explanation how it works internally to prevent misunderstandings (monkey-patching, store callbacks in internal array and so on). /cc @rstacruz

@rstacruz
Collaborator
rstacruz commented Apr 4, 2013

As an exercise, I tried to refactor jQuery.Turbolinks to remove the main 'complex' things that may need documentation (IMHO), $.setReadyEvent and $.setFetchEvent. Here's how it turned out: https://gist.github.com/rstacruz/5308599

(Not saying it should be merged in, but it kinda demonstrates how much impact one feature has made to the codebase.

@kossnocorp
Owner

@rstacruz current jQuery Turbolinks realisation is very flexible and can be used not only with original Turbolinks (for example @jokklan uses it with pjax). But I think it's be better to use your implementation in v2.0.0 because this is jQuery Turbolinks, but jQuery Anything. But v1.0.0 still can be used with pjax or anywhere else. What do you think about it?

@rstacruz
Collaborator
rstacruz commented Apr 4, 2013

I don't have a strong stance on the issue, really. :-)

Alternate take: how about in 2.0, consider API changes that would make documentation less necessary? Here's how it is now:

$.setFetchEvent('pjax:start');
$.setReadyEvent('pjax:end');
$.isReady;

Putting everything in a namespace might make things more obvious:

$.turbo.use('pjax:start', 'pjax:end');
$.turbo.isReady;

(Proof of concept: https://gist.github.com/rstacruz/5308759)

@kossnocorp
Owner

@rstacruz can you push this code into branch v2.0.0?

@rstacruz
Collaborator
rstacruz commented Apr 6, 2013

Done.

@rstacruz rstacruz closed this Aug 26, 2013
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.