Change IDL to be ReSpec compatible

[rmcilroy]

Addresses #24

[igrigorik]

Looks great! LGTM.

Preview: https://rawgit.com/rmcilroy/requestidlecallback/gh-pages/index.html

/cc @toddreifsteck @plehegar

[plehegar]

I'm sorry that I didn't catch this one earlier. The reason why respec doesn't parse pre class='idl' is because the WebIDL is invalid. You cannot use "optional" in a dictionary. see http://heycam.github.io/webidl/#prod-DictionaryMember . "On a given dictionary value, the presence of each dictionary member is optional, unless that member is specified as required." (from paragraph at http://heycam.github.io/webidl/#dfn-present). So the patch for #24 is to remove the keyword optional and respec will do the right things after that. Using dl/dt|dd for defining IDL is considered old school now (see http://www.w3.org/respec/guide.html#idl-in-trees) so my preference would be not to apply this PR but fix the IDL instead.

[igrigorik]

Anything blocking us from landing this? Since this is a cosmetic change we should be good to go?

[igrigorik]

@toddreifsteck @plehegar bump :)

[toddreifsteck]

Content looks good to me, but I'll defer to @plehegar for the merge as he gave previous feedback.

[plehegar]

Indeed, I would prefer not to merge here. Happy to sit down this week to sort this out.

[rmcilroy]

Is there any way to have the method descriptions in this change (e.g., https://rawgit.com/rmcilroy/requestidlecallback/idlchange/index.html#widl-Window-requestIdleCallback-unsigned-long-IdleRequestCallback-callback-IdleRequestOptions-options) with contiguous IDL?

I'll fix the invalid IDL as part of fixes I'm doing for #31, but @plehegar if you can do the other changes sometime this week that would be great.

[plehegar]

@rmcilroy by method description, you'd prefer to have the style used https://rawgit.com/rmcilroy/requestidlecallback/idlchange/index.html#widl-Window-requestIdleCallback-unsigned-long-IdleRequestCallback-callback-IdleRequestOptions-options
rather the style used in
https://w3c.github.io/requestidlecallback/
?
The answer is no, not really. I can propose something that would use separate sections but nothing closed to what the old idl style used. If you really prefer the old style, then we should merge this PR and make sure the respec folks won't remove the dl/dt/dd mechanisms.

[rmcilroy]

I'd rather use the new style rather than the old one, however the one nice thing about the old style was I could move some of the API description nearer the IDL descriptions, rather than having to have the description much further away from the IDL description (e.g., see the IdleDeadline didTimeout and timeRemaining descriptions).