Indeed! The Style System "it's complicated" :-) Gracias, Emilio
On Monday, January 2, 2017, Bobby Holley <bobbyhol...@gmail.com> wrote: > Of the 82 commits that landed on servo/servo this weekend, 73 were > emilio's. The combined patch weighed in at 540k, with 88 files changed, > 2747 insertions(+), 1001 deletions(-). > > Chapeau! > > On Mon, Jan 2, 2017 at 6:04 AM, Emilio Cobos Álvarez <emi...@crisal.io > <javascript:_e(%7B%7D,'cvml','emi...@crisal.io');>> wrote: > >> [Bcc dev-tech-layout, for potentially-interested stylo people, please >> follow-up on dev-servo] >> >> This week I've landed three PRs[1][2][3], that add documentation to most >> of the style system code, and uses the standard Rust compiler lints to >> force it on new code. Thanks Boris for filling[4], btw. >> >> There is surely documentation that needs to be expanded. Please file >> issues for underdocumented stuff, or fill the gaps if you can. >> >> The setup is as follows: >> >> All the public code needs to be documented, and this is enforced via the >> compiler (that is: no docs, no build). >> >> There are few private things that may not be caught by the lint and I've >> tried to document. There's no standard way that I know of for preventing >> non-pub code to be undocumented. Non-public code is not that common >> though, so hopefully reviewers will require it to land changes if the >> code is not straight-forward. >> >> There are a few exceptions to the docs-required lint though: >> >> * The media_queries module, which I'm rewriting as part of bug 1325878 >> (didn't want to write throwaway docs). >> >> * The atomic_refcell module, which Bobby was rewriting. >> >> * The attr module, which is mostly DOM-related code. >> >> Finally, there's all the property parsing code. That is a _huge_ amount >> of code, and when I went through the missing docs I found myself writing >> a lot of repetitive documentation (given they're mostly straight-forward >> representations of the spec text). That means the lint is disabled for >> those modules. >> >> I think what we may want to do there is requiring at least a spec link >> per property (and then comments as the author and reviewers see fit). >> Also, a big comment describing the current Mako setup for both Servo and >> Stylo (which is sort of weird for newcomers) would be helpful. >> >> These last two bits are not done yet, and I won't have the cycles to do >> them this week (and probably next week, because of exams), so if someone >> wants to jump in and do it, please feel free to do so! >> >> Thanks for reading, and thanks to the reviewers for the feedback and the >> fast turnaround time, which made this way easier to land than expected! >> >> -- Emilio >> >> [1]: https://github.com/servo/servo/pull/14801 >> [2]: https://github.com/servo/servo/pull/14802 >> [3]: https://github.com/servo/servo/pull/14819 >> [4]: https://github.com/servo/servo/issues/14765 >> >> _______________________________________________ >> dev-servo mailing list >> dev-servo@lists.mozilla.org >> <javascript:_e(%7B%7D,'cvml','dev-servo@lists.mozilla.org');> >> https://lists.mozilla.org/listinfo/dev-servo >> >> > _______________________________________________ dev-servo mailing list dev-servo@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-servo
