1000460 - Document the strongly-typed units system

Status: NEW

(Core :: Layout, defect)

Description

[Botond Ballo [:botond]]

We have a system of strongly-typed units in layout/base/Units.h, which consists of:

  - a set of geometric concepts (point, size, rect, margin, scale factor)

  - a templated base class for each concept which implements functionality 
    in a generic way (BasePoint, BaseRect, etc.)

  - a set of coordinate systems (CSS, LayoutDevice, Layer, Screen, with the
    possibility of other code defining other systems (e.g. APZ code defines
    "ParentLayer"))

  - concrete instances of the base classes for each coordinate system, and
    also separate ones for integer and floating-point coordinates
    (CSSPoint, CSSIntPoint, CSSRect, etc.)

The interfaces of these types are designed to catch coordinate-system-related
mistakes (e.g. a silent conversion from one coordinate system to another)
at compiler time as much as possible. We also have operators that combine
these types (for example, multiplying a CSSRect by a CSSToScreenScale yields
a ScreenRect) that try to preserve this safety as well.

Having this safety net is very useful and has caught a number of bugs and
potential bugs while working on platform code, particularly APZ code which
uses these units extensively. 

At the same time, I can see how a potential contributor trying to write code 
that works with points, rects, etc. but is not familiar with this system 
might find getting such code to compile to be a frustrating experience.

To make things easier for such contributors (and in general anyone using the
strongly-typed unit system), I recommend that we write some documentation
that describes the interfaces present in these types, and gives some example
code for accomplishing common operations.

If you have used or tried to use these strongly-typed unit classes, and found
something about them confusing or frustrating, please let me know by commenting
on this bug; this should inform what we document and at what level of detail.
(It might also suggest improvements to the interfaces themselves!)

Thanks to Doug Sherk for bringing this issue to my attention!

Comment 1

[Doug Sherk (:drs) (inactive)]

I just made a mistake by printing out a ParentLayerSize using %d and getting 0, thinking that it wasn't being initialized correctly. Botond pointed out that any units that don't have "Int" in their name are floats. This would be a nice thing to put in a "before you start working on code that uses these units" page.

Comment 2

[Botond Ballo [:botond]]

Unassigning for now, as I have more pressing bugs to work on, even in the "nice to have" category. I do hope to return to this at some point.