-
Notifications
You must be signed in to change notification settings - Fork 29.6k
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
Comments
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. |
@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. |
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.
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!) |
-1 on JSON-izing the docs. Closing. |
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. |
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.) |
Yes I'm volunteering to work on this but like I said, some kind of detailed method signature is needed. |
This would be interesting, but should probably now be pursued as a new issue in the docs WG. Thanks! |
I already mentioned this idea in the
node-forward
repository two months ago [1] but sinceIO.js
has been announced, I thought that I would rephrase it and repost it here.Currently the
Node.js
(andIO.js
too if I'm not mistaken) specifications are generated using the local NPM packagenode-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:i18n
templating engine helpers (e.g:handlebars-helper-i18n
in the case ofhandlebars.js
ÌO.js
site into another Git module that would make use of this JSON specificationThis 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:
I also imagine that generating
TypeScript
/Flow
/ATScript
definition files for the nativeIO.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 thetc-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#15The text was updated successfully, but these errors were encountered: