Added core/css/properties/README.md.

third_party/WebKit/Source/core/css/properties/README.md

+# Property APIs
+
+This directory contains implementations for CSS property APIs, as well as Utils
+files containing functions commonly used by the property APIs.
+
+A CSS property API represents a single CSS property or a group of CSS
+properties, and defines the logic for that property or group of properties.
+
+Examples:
+
+* A single property API: the `CSSPropertyAPILineHeight` class is used only by
+the `line-height` property
+* A group of properties that share logic: the `CSSPropertyAPIImage` class
+is shared by the `border-image-source` and `list-style-image` properties.
+
+Status: Eventually, all logic pertaining to a single property should be found only

[alancutter (OOO until 2018), 2017/03/13 04:53:01]

We should have a timestamp attached to the status so it'll be obvious when this
doc gets out of date.

[Bugs Nash, 2017/03/15 22:37:28]

Done.

+within its CSS property API. Currently, the code base is in a transitional state
+and property specific logic is still scattered around the code base. See Project
+Ribbon
+[tracking bug](https://bugs.chromium.org/p/chromium/issues/detail?id=545324) and
+[design doc](https://docs.google.com/document/d/1ywjUTmnxF5FXlpUTuLpint0w4TdSsjJzdWJqmhNzlss/edit#heading=h.1ckibme4i78b)
+for details of progress.
+
+## How to add a new property API

[alancutter (OOO until 2018), 2017/03/13 04:53:01]

Is there an example CL we can link to that follows all these steps?

[Bugs Nash, 2017/03/15 22:37:28]

Hm. All the CLs we've written are to create APIs for existing properties (and
move some parsing logic out of the parser to the new API). These steps describe
how to add a new property that was not previously implemented, which hasn't
happened in the new world yet. Do you think it would be useful to link one of
the CLs that move an existing property to the new API?

[alancutter (OOO until 2018), 2017/03/15 23:44:33]

Yes, I think a concrete CL showing places in the code is quite valuable.
Definitely make it clear it's migrating a property when linking to it rather
than adding a new one. For someone familiar with the old system it would
probably serve well as a Rosetta stone.

+
+1.  Add a .cpp file to this directory named
+    `CSSPropertyAPI<Property/GroupName>.cpp`
+2.  Implement the property API in the .cpp file
+    1.  Add `#include "core/css/properties/CSSPropertyAPI<Property/GroupName>.h"`
+        (this will be a generated file)
+    2.  Implement the required methods on the API, e.g. `parseSingleValue`
+3.  If logic is required by multiple property APIs you may need to create a new
+    Utils file.
+4.  Add new property to `core/css/CSSProperties.json5` (see
+    [CSSProperties.json5](https://cs.chromium.org/chromium/src/third_party/WebKit/Source/core/css/CSSProperties.json5)
+    for details)

[alancutter (OOO until 2018), 2017/03/13 04:53:01]

This doc ought to mention the api_class flag as a requirement for using the
CSSPropertyAPI.

[Bugs Nash, 2017/03/15 22:37:28]

I have added a mention that api_class and api_methods are required (but not
explained how to add them). This is because it seems like the requirements of
these flags might change, so I want to minimize the information that might go
out of date in this doc. Given that the specifics are described in
CSSProperties.json5 I figure it doesn't need to be repeated here.

+5.  Add new files to BUILD files
+    1.  Add the new .cpp file to
+        [core/css/BUILD.gn](https://codesearch.chromium.org/chromium/src/third_party/WebKit/Source/core/css/BUILD.gn)
+        in the `blink_core_sources` target's `sources` parameter
+    2.  Add the generated .h file to
+        [core/BUILD.gn](https://codesearch.chromium.org/chromium/src/third_party/WebKit/Source/core/BUILD.gn)
+        in the `css_properties` target's `outputs` parameter