[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
signature.asc
Description: PGP signature
_______________________________________________ dev-servo mailing list dev-servo@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-servo
