search

dart-lang / sdk

The Dart SDK, including the VM, JS and Wasm compilers, analysis, core libraries, and more.
https://dart.dev
BSD 3-Clause "New" or "Revised" License
10.11k stars 1.56k forks source link

Copying documentation from lib.dom.d.ts to dart #22948

Open DartBot opened 9 years ago

DartBot commented 9 years ago

This issue was originally filed by kasperpeul...@gmail.com

One thing I would like to see, is having the dom api's being documentated in the dart language. Of course, mdn is a great source, but personally I do much coding offline in the train, and even if I'm online, I love the ability to having the documentation and the code side by side in the IDE, instead of googling everything.

Now, I see that typescript has also started the task of documentating the dom apis. Just like for dart:html, it isn't complete, but it has a bit more covered currently I think. See the screenshot for an example.

This is the file that typescript uses: https://github.com/Microsoft/TypeScript/blob/master/bin/lib.dom.d.ts I think about copying the typescript documentation into the dart sdk, if this is legally possible. I think about doing it by hand, as it would probably be great for learning more about the dom APIs.

I've read this: https://code.google.com/p/dart/wiki/ContributingHTMLDocumentation which doesn't seem that difficult.

Would you guys appreciate a documentation pull request where I use the documentation from https://github.com/Microsoft/TypeScript/blob/master/bin/lib.dom.d.ts ?

Attachment: documentation.png (57.27 KB)

DartBot commented 9 years ago

This comment was originally written by kasperp...@gmail.com

This is also an interesting source for such a task: https://github.com/marijnh/tern/blob/28af2f7db9e53584bb60b4359acb6dafc088cf5e/defs/browser.json

DartBot commented 9 years ago

This comment was originally written by @alan-knight

We would definitely appreciate getting more docs, but it's complicated. Probably there are some things we should do first.

It sounds like you've already figured a lot of this out, but the HTML libraries come in two versions, and those are generated out of Chrome IDL using some rather messy Python scripts. The current dartdocs pull the comments out of the dart2js version of those libraries. We also used to pull comments out of MDN, but MDN isn't very consistently structured, so the way we did it was rather complicated and it's been broken for the last while.

There's a little dance to add comments to things that are @­DocsEditable. So you could do that by hand, but I wouldn't recommend it. Better would be if we can pull things in an ongoing basis, so as the Typescript docs were updated we could also pull in that information, and combine it with hand-written docs and whatever other sources we have.

The way we were pulling in the MDN docs was via a JSON file, so it's possible that we could do something in the short term by just converting the format of the typescript doc JSON file to match what the MDN-scraping code was emitting. That's probably a bit of an undertaking, but less than doing the whole DOM by hand. And if you wanted to work on it we would certainly appreciate that.

I'm assuming that there aren't any legal issues associated with it. There might also be issues if the Typescript docs are referring to TypeScript types that don't exist, or are differently named, in Dart. And the API's might be different, because I think the Typescript DOM reflects what's in IE, and the Dart one what's in Chrome, so APIs that aren't fully standardized yet may differ.

alan-knight commented 9 years ago

Set owner to @alan-knight. Added Library-Html, Area-Library, Accepted labels.

DartBot commented 9 years ago

This comment was originally written by kasperpeul...@gmail.com

I see now that there is also this file: https://github.com/Microsoft/TypeScript/blob/master/src/lib/dom.generated.d.ts

This is the same, but without the IE10 and IE11 extensions. The reason that typescript has so much covered is probably, because their dom definition files seem to be generated from the microsoft dom documentation. I'm not sure though if this documentation is open source.

The way we were pulling in the MDN docs was via a JSON file, so it's possible that we could do something in the short term by just converting the format of the typescript doc JSON file to match what the MDN-scraping code was emitting. That's probably a bit of an undertaking, but less than doing the whole DOM by hand. And if you wanted to work on it we would certainly appreciate that.

I don't think I'm the right guy for that job at the moment, I may take that as a challenge this summer, but I'm not an experienced programmer. I don't mind doing it by hand, because I think it would help me learn more about the DOM api.

But I understand that reinventing the wheel may not be the best solution, especially as there also other projects documentating the dom. This project from the creator of codemirror has also done quite some work: https://github.com/marijnh/tern/blob/28af2f7db9e53584bb60b4359acb6dafc088cf5e/defs/browser.json

I read that this is handwritten from MDN, probably for the same reason that is hard to extract comments out of MDN. It is a nice json format as well. It doesn't seem as complete as typescript, but it may be not that difficult to convert this json file to a format that dart understand.

DartBot commented 9 years ago

This comment was originally written by kasperp...@gmail.com

This may be interesting, the typescript dom definitions in json format: https://raw.githubusercontent.com/artifacthealth/tsreflect-compiler/master/lib/lib.dom.d.json

alan-knight commented 9 years ago

Well, if you want to do some manually that would certainly be appreciated too. I'd suggest doing a small number as a trial run to make sure to get the process down properly.

DartBot commented 9 years ago

This comment was originally written by kasperpeulen...@gmail.com

@alanknight

I've been playing around with the docs.webplatform.org api today, and I think this may be a better solution than using mdn or typescript definition files.

The api of the webplatform is quite excellent. I'm not 100% sure how the quality of web platform compares with mdn, but to give an example how to use the web platform API, here is a dartpad that generates documentation for css3 properties: https://dartpad.dartlang.org/f1eeb2b1f6b4cf7703e0

I think that generating dom documentation with this API will work similar. Thoughts about this ?

alan-knight commented 9 years ago

My understanding is that docs.webplatform.org is better structured, but the content isn't as good. I don't know how quantified that is, but if it's easy enough it might be worth doing the experiment and seeing how well the content comes out.

DartBot commented 9 years ago

This comment was originally written by kasperp...@gmail.com

You can get a json, so I guess that is as structured as it get :)

I think it is not as complete as mdn, but what I've seen, it is not that bad at all. Besides, I was thinking, if we start from that, if someone (me for example ;) ) wants to contribute to the dart:html documentation, he could just contribute to docs.webplatform and then it automatically will end up at dart as well.