PSA: Style system changes now require documentation.

classic Classic list List threaded Threaded
1 message Options
Reply | Threaded
Open this post in threaded view
Report Content as Inappropriate

PSA: Style system changes now require documentation.

Emilio Cobos Álvarez
[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-tech-layout mailing list
[hidden email]

signature.asc (499 bytes) Download Attachment