Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

JSON API specification #520

Closed
Mickael-van-der-Beek opened this issue Jan 20, 2015 · 8 comments
Closed

JSON API specification #520

Mickael-van-der-Beek opened this issue Jan 20, 2015 · 8 comments
Labels
doc Issues and PRs related to the documentations.

Comments

@Mickael-van-der-Beek
Copy link

I already mentioned this idea in the node-forward repository two months ago [1] but since IO.js has been announced, I thought that I would rephrase it and repost it here.

Currently the Node.js (and IO.js too if I'm not mistaken) specifications are generated using the local NPM package node-doc-generator developed by @isaacs almost three years ago.

This module generates HTML by parsing the markdown language using some simple rules.

In my opinion, the process should be the other way around. The API reference should be specified in some kind of pre-agreed upon JSON structure that would also be exposed to the IO.js API. Doing this would have the following advantages:

    1. If you have a JSON data source (the specification), you can easily render the HTML using a templating engine like any other website.
    1. Designers would already be used to this kind of site "architecture" which makes it much easier for them to contribute.
    1. Internationalisation could be easily integrated by using already proved solutions like i18n templating engine helpers (e.g: handlebars-helper-i18n in the case of handlebars.js
    1. It gives you the possibility of separating the ÌO.js site into another Git module that would make use of this JSON specification

This would only be a first step. Here a two examples of tools that I'd like to develop as a follow-up and that would be possible thanks to the JSON specification mentioned above:

  • fuzz testing and dynamic test generation to test the native API's parameter validation as well as error returning / throwing
  • debug module that intercepts native API calls and throws verbose, explicit errors in case of invalid input data

I also imagine that generating TypeScript/Flow/ATScript definition files for the native IO.js API would be more automatic and version controlled.

Anyway, I think that a JSON specification could have a lot of use cases both in the core API as well as a data source for package developers.
I also believe that a stricter specification would limit the number of GitHub issues opened due to strange behaviours encountered in cases where parameters were not validated correctly.
(For some examples you can click on my original post. [1])

As I said in the previous thread, since it's not a C/C++ feature, I'd be willing to contribute actively.

Since this subject was in part talked about in the last IO.js TC meeting, I thought that this issue could get the tc-agenda GitHub label so that this issue could move forward quicker.
I will by the way attend the next IO.js TC meeting on the 21/01/2015.

Also, if we ever need help on the design side of the site, I can ask my company's designer.

[1] Link to the original node-forward thread: node-forward/discussions#15

@chrisdickinson
Copy link
Contributor

I am more amenable to something like this if it's supplemental to the existing doc structure, instead of replacing it.

Docs should be designed to be consumed (and edited) primarily by humans and secondarily by tooling; I'm generally -1 on doctests, interspersing our existing docs into the codebase, or authoring the docs in a non-human-centric format. Conflating type annotation with documentation will serve those who need API docs poorly – it's hard to cater to computers and humans at the same time. The two audiences require that the subject be organized and treated differently.

The documentation generation should improve; but I'd like to see them improve along the lines of what sphinx (see also readthedocs) or asciidoctor offer.

@Mickael-van-der-Beek
Copy link
Author

@chrisdickinson I agree with you that a documentation system should be developed with humans in mind first and tooling second. The idea I was proposing goes in that direction.

This JSON specification I was talking about earlier would be created by humans manually in separated fies outside of the source code like the markdown files are now, not generated with some kind of JSDoc-like system.

It still gives the human the possibility to write the raw specification like types and formats in JSON but the presentation layer is then rendered with a templating engine (or even Sphinx and other systems) using the JSON structure as the data source.

The issue is that if no IO.js parsable spec is used, it won't be possible for example to generate input validation tests automatically. The API growing, the amount of test cases needed to cover all these cases will be enormous and unmanageable without dynamic test generation.
Fuzzing could also be very useful for bug discovery.

@chrisdickinson
Copy link
Contributor

This JSON specification I was talking about earlier would be created by humans manually

Editing JSON by hand is not human-centric. JSON is meant to be written and read primarily by machines; humans take a distant second place. It cannot handle text formatting (by which I mean newlines to wrap lines), it does not lend itself to textual editing, and common punctuation requires escaping.

We use markdown over HTML because the most important thing during the authoring and editing process is the idea being conveyed – the markup is a secondary concern, and the way we render it tertiary to both. Markdown (or ReST, or Asciidoc) look and act like a textual document in their source form and in their ultimate rendered form. JSON looks like a textual document only after its been rendered to something else. I am very much against replacing the markdown docs with JSON.

The issue is that if no IO.js parsable spec is used, it won't be possible for example to generate input validation tests automatically.

That starts to get into the realm of type annotation, which I'm okay with formalizing a bit better in the existing markdown docs (we can improve the tool to pick these things up more easily).

It would be useful to talk about specifically what kind of information is missing from the docs that we could start to formalize. It may very well be possible to generate JSON you require from the markdown we have (or could have!)

@Fishrock123 Fishrock123 added the doc Issues and PRs related to the documentations. label Jan 22, 2015
@Fishrock123
Copy link
Contributor

-1 on JSON-izing the docs. Closing.

@Mickael-van-der-Beek
Copy link
Author

Any suggestions on automated testing and fuzzing for IO.js input validation if there's no JSON spec to derive the input from ?

The JSON spec was one way to structure and make the core method signatures easy to extract.

@Fishrock123
Copy link
Contributor

I'm really not sure core would be willing to take that work on... (are you volunteering yourself? there are a good amount of changes that come in and out and it would be preferably not to increase friction there.)

@Mickael-van-der-Beek
Copy link
Author

Yes I'm volunteering to work on this but like I said, some kind of detailed method signature is needed.

@Fishrock123 Fishrock123 reopened this Apr 29, 2015
@Fishrock123 Fishrock123 changed the title More advanced JSON API specification and documentation JSON API specification Apr 29, 2015
@brendanashworth
Copy link
Contributor

This would be interesting, but should probably now be pursued as a new issue in the docs WG. Thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
doc Issues and PRs related to the documentations.
Projects
None yet
Development

No branches or pull requests

4 participants