"API Specification" Style Documentation

[76784]

I would love to see API Specification style documentation for Sinon, along the lines of what you see in Java (the gold standard of documentation), or jQuery.

An A-Z alphabetical list of functionality, written in a non-conversational way (which is how the current documentation is currently written) is what this documentation needs.

[76784]

By the way, I'm not harping on the current documentation, which is valuable. I'm merely suggesting an additional, comprehensive thing.

[mantoni]

Java has automatic tools to generate JavaDocs without manual work. To achieve something like this in a JS library requires a ton of manual work. I'd love to see something like it, but I fear it would outdate pretty quickly.

We could bikeshed about code annotations and tooling a little. Maybe there are viable options.

[76784]

I know it's been brought up on other threads, but I think, very simply, that the entire library should be documented with jsDoc. It is something of a defacto standard for JavaScript (or, at least, the strongest argument there is for one). We could just publish the api starting with mimimal documentation coverage, and put a big "in progress" sign on the wall, and build from there.

[fatso83]

@mantoni There are lots of tools for auto-generating JSDocs. I don't see a v1 of this to be an issue. You don't need to create @typedefs everywhere. Just having

/**
  @param {String} [foo] optional string
  @example Create foo instance
       var foo = dooFoo('somestring') 
*/ 

would help quite a bit.

[lucasfcosta]

Hi @76784, that's great input! 😊

I have, however, a few considerations to make.

I quite like JSDoc. That's also what we use on Chai.js and it's worked pretty well so far due to being able to separate things into namespaces and always keep code in sync with docs since they're right next to each other.

However, I'd disagree that Java's documentation is the "gold standard". I find Java docs to be very dry. It's good for reference, but bad for learning or groking bigger parts of it. I like the fact that docs for Sinon are written in friendly plain-text classical style. IMO that helps driving adoption. Also, as an API reference they're pretty good IMO.

I think would be good, of course, to have JSDocs, but it's important to notice that it would require an extremely significant effort.

[fatso83]

If @76784 would start a branch and flesh out some concepts, I think some people attracted to the idea could quickly latch onto it and help out. The API surface isn't that big.

[76784]

@lucasfcosta

I find Java docs to be very dry. It's good for reference, but bad for learning or groking bigger parts of it.

I don't disagree. I'm merely saying that the two things - documentation and tutorial - should be separate things. The dryness of javadocs is a plus. One is able to go there and find out, through this dry-language convention, what the "thing" does. And of course, most importantly, it is comprehensive in nature. I don't want wordy sentence structure in my documentation - I want that in my tutorial.

I'm not an expert in JSDoc, but I wonder if in the JSDoc comments there would be an easy way to link to the tutorial for the entry.

As for contributing some proofs-of-concept on this, @fatso83 , I'm a bit short of time at the moment (I know, who isn't?), but I might be in a better position to later in the year. It would be a great way to learn Sinon thoroughly.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[mroderick]

I’ve pinned this issue, so it doesn’t get closed by Stale bot

[mroderick]

If we do decide to go down this road, then I think we should use something like https://github.com/gajus/eslint-plugin-jsdoc ... the rules should probably go into eslint-config-sinon.

[76784]

Sorry to dive in and out of this - it's really driven by some work priorities. And I don't know if this is the right thread, but just to offer some more feedback on the existing documentation...

As I look at something like spies: https://sinonjs.org/releases/v7.4.1/spies/

I happen to be working with Mocha, which has a different syntax from what is shown in the first chunk.

"test should call subscribers on publish": function () {
    var callback = sinon.spy();
    PubSub.subscribe("message", callback);

    PubSub.publishSync("message");

    assertTrue(callback.called);
}

The fact that I'm using Mocha instead of whatever that is (Jasmine?) is no biggie. They're obviously similar. But what does make that example hard to understand is that you don't show the function that is being tested.

That is something I think should be done if you're going to provide examples. Show the minimum working functionality of whatever thing is being tested. Same issue here, with myLib: https://sinonjs.org/releases/v7.4.1/fake-xhr-and-server/

I get it - myLib is something I would write. But you're asking a lot of the newbie to have to learn this stuff without seeing any of what they're testing against.

[fatso83]

Actually that test IS using Mocha's syntax, you're just using the more standard BDD style (of the two) :-) It's also shared by some other libraries, such as Buster JS, which Sinon's original creator also (co-)created. Anyway, it would probably make sense for someone to update all the examples to the most common style in use :-)

As to the other points, these are quite valid, and something we have discussed. Actually, we discussed having runnable, tested, embedded examples, guaranteeing validity. Which implicitly would fix those issues. But yeah, someone needs to sit down and do it ...

[76784]

Actually that test IS using Mocha's syntax

What?? Now I'm going to have to go rant about the Mocha documentation. :-)

[mroderick]

I've tried to start this effort in sinonjs/samsam#82. Your comments welcome, please post them on that PR.