search

jpmedley / mdn-helper

Removes repetitive work of creating MDN boilerplate markup and text.
Apache License 2.0
5 stars 3 forks source link

Pull data from spec to automatically answer some of those questions #4

Open a2sheppy opened 5 years ago

a2sheppy commented 5 years ago

Of all the questions that get asked while generating the HTML output, a good percentage of them can be answered by pulling information from the WebIDL for the specification. There are npm modules for scraping the WebIDL out of a spec, so this tool should use that to obtain the definitions of methods and properties.

Once that's been obtained, the tool can automatically generate:

Possibly some other stuff too. But that would take a lot of the work out of it for the user when actually doing the content generation.

jpmedley commented 5 years ago

Do you have a preference on which to do first?

jpmedley commented 5 years ago

Pulling IDL from specs is problematic. I have been asked not to document features that don't yet exist in a browser. I don't think my bosses would be enthusiastic about me devoting time to automating exactly that functionality.

a2sheppy commented 5 years ago

Pulling IDL from specs is problematic. I have been asked not to document features that don't yet exist in a browser. I don't think my bosses would be enthusiastic about me devoting time to automating exactly that functionality.

I'm not talking about having a tool that automatically does this every day or something. I'm talking about a tool that uses the IDL from a spec to get this information on demand.

Say I know that the Web Audio API has a new kind of node defined called a WhiteNoiseNode. It's been implemented by Chrome, and Firefox has an implementation arriving soon. Time to document it! Right now, I manually compose the data or use a tool like this one, where I have to manually enter a bunch of info that's found in the spec. What I propose is that the tool could instead be enhanced to pull the WebIDL for WhiteNoiseNode from the spec and get a lot of the information this tool needs automatically.

a2sheppy commented 5 years ago

@jpmedley - Okay, I see now.

So actually what it comes down to is that we have differing goals. My goal is to document everything, regardless of whether or not Firefox implements it, if the spec is stable and/or it's implemented by more than one browser. That's a different situation than you're in (which is a perfectly understandable case; you guys have a different priority model than we do).

That leaves me in a pickle. This tool is off to a great start but is really designed to document Chrome. But you're creating pages for posting on MDN, which doesn't only document Chrome -- it needs to also cover Edge, Firefox, Safari, Opera, Node, and others, so the result is pages that have to be updated further to include stuff you guys don't implement. But since the pages are already up, we can't just use a too to automatically generate skeletons anymore since the pages are in place and have gone through some amount of manual updating since being created.

Since several of those browsers use the same engine as Chrome, there's some synchronicity there, but they don't all use the same versions. Plus of course there's WebKit and Gecko. And who knows what else could come later...

Basically for automation purposes, I will either need to fork this and make substantial changes to switch it over to using the spec as a source instead of Chrome's IDL, or continue to work gradually toward trying to build a totally separate tool (I started on one a while back but had stopped when I saw you working on this).

jpmedley commented 5 years ago

I'll work with any data source that reflects an actual implementation. This was designed with that in mind. (It will require some work.) I just won't work with anything that's unimplemented.