search

w3c / requestidlecallback

Cooperative Scheduling of Background Tasks
https://w3c.github.io/requestidlecallback/
Other
50 stars 19 forks source link

Change IDL to be ReSpec compatible #30

Closed rmcilroy closed 8 years ago

rmcilroy commented 8 years ago

Addresses #24

igrigorik commented 8 years ago

Looks great! LGTM.

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

/cc @toddreifsteck @plehegar

plehegar commented 8 years ago

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 commented 8 years ago

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

igrigorik commented 8 years ago

@toddreifsteck @plehegar bump :)

toddreifsteck commented 8 years ago

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

plehegar commented 8 years ago

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

rmcilroy commented 8 years ago

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 commented 8 years ago

@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 commented 8 years ago

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).