Documentation in JavaScript

[keirlawson]

I think many potential users of this library will be using JavaScript rather than CoffeeScript. Having to mentally-transpile the examples in the existing documentation make it hard to read for somebody wanting to use the library with JS so it would be nice if we also had examples using JS, perhaps side by side?

[bigmeech]

+1

[Brian-A]

+1 - very confusing for people who've never seen CoffeeScript

[notatestuser]

"Very confusing" – really?

[bigmeech]

@keirlawson @Brian-Aykut I ended up using nodegit. Superb documentation FYI http://www.nodegit.org/api/

[Brian-A]

@notatestuser yes - I ended up running what I could through the http://coffeescript.org/ "try coffeescript" feature, then using CLI/exec for the items I needed, I tried nodegit as well @bigmeech (cheers for the suggestion), would have loved to use a solution like that, but the features I needed would have required more low level stuff than I had the time/inclination to spend time on learning unfortunately

[notatestuser]

Could you give an example of something you find confusing in the documentation? It's possible I've developed a CoffeeScript transpiler in my brain at this point but really I can't see how the JS counterpart method signatures (and etc) wouldn't be obvious. Or is it the small code samples you have issue with? e.g.

git.init "path/to/repo", (err, _repo) ->
  repo = _repo
  # => #<Repo>

We can change those

[Brian-A]

To be honest it was mainly that I didn't know it was CoffeeScript as there wasn't any mention of it in the docs, as such I had no resource to translate it into something I understood. I probably should have looked at the source but I'd initially found this package via the NPM site, and skipped straight to the docs.

The method signatures are easy enough to figure out for the most part, it's mainly the code examples are different enough to their native JS counterparts especially when passing an anonymous function as an argument to look a little alien to someone unfamiliar with CoffeeScript.

I think side by side examples as @keirlawson suggested at least for the first 5 examples would definitely help clarify this as it's likely the first place someone will look if trying to use the library.

[rista404]

+1

[erikyuzwa]

+10

[djabraham]

I hate to pile on, but there seems to be a lack of empathy here.

The purpose of documentation is to be readable, not to impress others one's mastery in a fringe language of dubious value. The documentation appears to have elements of ES6 and Coffee intermingled. I can't tell at a glance if a method is sync or async.

Using another lib might be an option for some; but unfortunately, someone already baked this thing into a standard JS project and I now have to back it out. I would rather not forgo learning important things to assimilate coffee right now.

[notatestuser]

Everything is async - it's node.js*. The syntax should be very similar to ES6 - is there something you're specifically having issues with?

Understand that this is an older project; its documentation was written when CoffeeScript was still taking off. Unfortunately we've not had anyone translate it to ES6 yet. As always, pull requests are accepted!

* fs.readFileSync and friends are exceptions to this rule, but we don't do anything synchronously unless specifically stated. This is a common convention in node.js libraries.