On Tue, Sep 15, 2015 at 5:51 PM, Fabrice Desré <fabr...@mozilla.com> wrote: > On 09/15/2015 07:24 AM, Ehsan Akhgari wrote: >> On 2015-09-15 7:31 AM, Paul Rouget wrote: >>> I believe the WebIDL files should play this role. But they are missing >>> comments and events. >> >> WebIDL files are not a suitable place for documentation to live, since >> they require review from DOM peers who are typically overloaded >> individuals, and it would be nice to not make them review documentation >> changes. > > That's also not where localizers expect to find their reference > material, and not where they could publish translations.
WebIDL should not replace the documentation. I’m saying WebIDL could play the role of a specification, a reference. You need something to start documenting an API. MDN editors can’t just guess what methods do and what events exist. HTML and Web APIs have a specification. The browser API has nothing. Maybe WebIDL is not the right place. I actually don’t care where this lives. But we need a reference/spec. Otherwise, the documentation will always be behind, and the Servo implementation will diverge. And if this reference is outside of m-c, we should, somehow, enforce updating the reference when events/methods are added/removed/modified. Any suggestion? -- Paul _______________________________________________ dev-b2g mailing list dev-b2g@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-b2g
