Import Cobalt 21.master.0.253153
diff --git a/src/third_party/skia/site/dev/contrib/style.md b/src/third_party/skia/site/dev/contrib/style.md
index 639738c..9edf83d 100644
--- a/src/third_party/skia/site/dev/contrib/style.md
+++ b/src/third_party/skia/site/dev/contrib/style.md
@@ -2,17 +2,17 @@
=======================
These conventions have evolved over time. Some of the earlier code in both
-projects doesn’t strictly adhere to the guidelines. However, as the code evolves
+projects doesn't strictly adhere to the guidelines. However, as the code evolves
we hope to make the existing code conform to the guildelines.
Files
-----
-We use .cpp and .h as extensions for c++ source and header files. We use
-foo_impl.h for headers with inline definitions for class foo.
+We use .cpp and .h as extensions for c++ source and header files.
-Headers that aren’t meant for public consumption should be placed in src
-directories so that they aren’t in a client’s search path.
+Headers that aren't meant for public consumption should be placed in src
+directories so that they aren't in a client's search path, or in
+include/private if they need to be used by public headers.
We prefer to minimize includes. If forward declaring a name in a header is
sufficient then that is preferred to an include.
@@ -22,8 +22,9 @@
<span id="no-define-before-sktypes"></span>
Do not use #if/#ifdef before including "SkTypes.h" (directly or indirectly).
+Most things you'd #if on tend to not yet be decided until SkTypes.h.
-We use spaces not tabs (4 of them).
+We use 4 spaces, not tabs.
We use Unix style endlines (LF).
@@ -41,7 +42,7 @@
------
Both projects use a prefix to designate that they are Skia prefix for classes,
-enums, structs, typedefs etc is Sk. Ganesh’s is Gr. Nested types should not be
+enums, structs, typedefs etc is Sk. Ganesh's is Gr. Nested types should not be
prefixed.
<!--?prettify?-->
@@ -54,7 +55,7 @@
};
~~~~
-Data fields in structs, classes, unions begin with lowercase f and are then
+Data fields in structs, classes, unions begin with lowercase f and are then
camel capped.
<!--?prettify?-->
@@ -81,7 +82,8 @@
Enum values are prefixed with k. Unscoped enum values are post fixed with
an underscore and singular name of the enum name. The enum itself should be
singular for exclusive values or plural for a bitfield. If a count is needed it
-is k<singular enum name>Count and not be a member of the enum (see example):
+is `k<singular enum name>Count` and not be a member of the enum (see example),
+or a kLast member of the enum is fine too.
<!--?prettify?-->
~~~~
@@ -98,7 +100,7 @@
kBlueberry_PancakeType,
kPlain_PancakeType,
kChocolateChip_PancakeType,
-
+
kLast_PancakeType = kChocolateChip_PancakeType
};
@@ -167,8 +169,8 @@
#define GR_GL_TEXTURE0 0xdeadbeef
~~~~
-Ganesh prefers that macros are always defined and the use of #if MACRO rather than
-#ifdef MACRO.
+Ganesh prefers that macros are always defined and the use of `#if MACRO` rather than
+`#ifdef MACRO`.
<!--?prettify?-->
~~~~
@@ -179,14 +181,14 @@
#endif
~~~~
-Skia tends to use #ifdef SK_MACRO for boolean flags.
+Skia tends to use `#ifdef SK_MACRO` for boolean flags.
Braces
------
-Open braces don’t get a newline. “else” and “else if” appear on same line as
+Open braces don't get a newline. `else` and `else if` appear on same line as
opening and closing braces unless preprocessor conditional compilation
-interferes. Braces are always used with if, else, while, for, and do.
+interferes. Braces are always used with `if`, `else`, `while`, `for`, and `do`.
<!--?prettify?-->
~~~~
@@ -227,7 +229,7 @@
Flow Control
------------
-There is a space between flow control words and parentheses and between
+There is a space between flow control words and parentheses and between
parentheses and braces:
<!--?prettify?-->
@@ -252,7 +254,7 @@
...
break;
case kGreen:
- ...
+ ...
break;
...
default:
@@ -284,7 +286,7 @@
switch (filter) {
...
case kGaussian_Filter: {
- Bitmap srcCopy = src->makeCopy();
+ Bitmap srcCopy = src->makeCopy();
...
break;
}
@@ -296,9 +298,9 @@
-------
Unless there is a need for forward declaring something, class declarations
-should be ordered public, protected, private. Each should be preceded by a
-newline. Within each visibility section (public, private), fields should not be
-intermixed with methods.
+should be ordered `public`, `protected`, `private`. Each should be preceded by a
+newline. Within each visibility section (`public`, `private`), fields should not be
+intermixed with methods. It's nice to keep all data fields together at the end.
<!--?prettify?-->
~~~~
@@ -308,14 +310,14 @@
...
protected:
- ...
-
-private:
- SkBar fBar;
...
+private:
void barHelper(...);
...
+
+ SkBar fBar;
+ ...
};
~~~~
@@ -330,8 +332,8 @@
};
~~~~
-Virtual functions that are overridden in derived classes should use override
-(and not the override keyword). The virtual keyword can be omitted.
+Virtual functions that are overridden in derived classes should use override,
+and the virtual keyword should be omitted.
<!--?prettify?-->
~~~~
@@ -339,8 +341,8 @@
}
~~~~
-This should be the last element of their private section, and all references to
-base-class implementations of a virtual function should be explicitly qualified:
+All references to base-class implementations of a virtual function
+should be explicitly qualified:
<!--?prettify?-->
~~~~
@@ -351,9 +353,6 @@
}
~~~~
-As in the above example, derived classes that redefine virtual functions should
-use override to note that explicitly.
-
Constructor initializers should be one per line, indented, with punctuation
placed before the initializer. This is a fairly new rule so much of the existing
code is non-conforming. Please fix as you go!
@@ -367,7 +366,7 @@
}
~~~~
-Constructors that take one argument should almost always be explicit, with
+Constructors that take one argument should almost always be explicit, with
exceptions made only for the (rare) automatic compatibility class.
<!--?prettify?-->
@@ -379,7 +378,7 @@
};
~~~~
-Method calls within method calls should be prefixed with dereference of the
+Method calls within method calls should be prefixed with dereference of the
'this' pointer. For example:
<!--?prettify?-->
@@ -387,47 +386,6 @@
this->method();
~~~~
-Comparisons
------------
-
-We prefer that equality operators between lvalues and rvalues place the lvalue
-on the right:
-
-<!--?prettify?-->
-~~~~
-if (7 == luckyNumber) {
- ...
-}
-~~~~
-
-However, inequality operators need not follow this rule:
-
-<!--?prettify?-->
-~~~~
-if (count > 0) {
- ...
-}
-~~~~
-
-Comments
-
-We use doxygen-style comments.
-
-For grouping or separators in an implementation file we use 80 slashes
-
-<!--?prettify?-->
-~~~~
-void SkClassA::foo() {
- ...
-}
-
-////////////////////////////////////////////////////////////////
-
-void SkClassB::bar() {
- ...
-}
-~~~~
-
Integer Types
-------------
@@ -435,16 +393,16 @@
(http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#Integer_Types)
-Summary: Use int unless you have need a guarantee on the bit count, then use
-stdint.h types (int32_t, etc). Assert that counts, etc are not negative instead
-of using unsigned. Bitfields use uint32_t unless they have to be made shorter
+Summary: Use `int` unless you have need a guarantee on the bit count, then use
+`stdint.h` types (`int32_t`, etc). Assert that counts, etc are not negative instead
+of using unsigned. Bitfields use `uint32_t` unless they have to be made shorter
for packing or performance reasons.
-nullptr, 0
--------
+`nullptr`, 0
+------------
-Use nullptr for pointers, 0 for ints. We prefer explicit nullptr comparisons when
-checking for nullptr pointers (as documentation):
+Use `nullptr` for pointers, 0 for ints. We suggest explicit `nullptr` comparisons when
+checking for `nullptr` pointers, as documentation:
<!--?prettify?-->
~~~~
@@ -453,8 +411,8 @@
}
~~~~
-When checking non-nullptr pointers explicit comparisons are not required because it
-reads like a double negative:
+When checking non-`nullptr` pointers we think implicit comparisons read better than
+an explicit comparison's double negative:
<!--?prettify?-->
~~~~
@@ -463,66 +421,27 @@
}
~~~~
-Returning structs
------------------
-
-If the desired behavior is for a function to return a struct, we prefer using a
-struct as an output parameter
-
-<!--?prettify?-->
-~~~~
-void modify_foo(SkFoo* foo) {
- // Modify foo
-}
-~~~~
-
-Then the function can be called as followed:
-
-<!--?prettify?-->
-~~~~
-SkFoo foo;
-modify_foo(&foo);
-~~~~
-
-This way, if return value optimization cannot be used there is no performance
-hit. It also means that modify_foo can actually return a boolean for whether the
-call was successful. In this case, initialization of foo can potentially be
-skipped on failure (assuming the constructor for SkFoo does no initialization).
-
-<!--?prettify?-->
-~~~~
-bool modify_foo(SkFoo* foo) {
- if (some_condition) {
- // Modify foo
- return true;
- }
- // Leave foo unmodified
- return false;
-}
-~~~~
-
Function Parameters
-------------------
-Mandatory constant object parameters are passed to functions as const references
-if they are not retained by the receiving function. Optional constant object
-parameters are passed to functions as const pointers. Objects that the called
-function will retain, either directly or indirectly, are passed as pointers.
-Variable (i.e. mutable) object parameters are passed to functions as pointers.
+Mandatory constant object parameters are passed to functions as const references.
+Optional constant object parameters are passed to functions as const pointers.
+Mutable object parameters are passed to functions as pointers.
+We very rarely pass anything by non-const reference.
<!--?prettify?-->
~~~~
// src and paint are optional
-void SkCanvas::drawBitmapRect(const SkBitmap& bitmap, const SkIRect* src,
- const SkRect& dst, const SkPaint* paint = nullptr);
+void SkCanvas::drawBitmapRect(const SkBitmap& bitmap, const SkIRect* src,
+ const SkRect& dst, const SkPaint* paint = nullptr);
+
// metrics is mutable (it is changed by the method)
SkScalar SkPaint::getFontMetrics(FontMetric* metrics, SkScalar scale) const;
-// A reference to foo is retained by SkContainer
-void SkContainer::insert(const SkFoo* foo);
+
~~~~
-If function arguments or parameters do not all fit on one line, they may be
-lined up with the first parameter on the same line
+If function arguments or parameters do not all fit on one line, the overflowing
+parameters may be lined up with the first parameter on the next line
<!--?prettify?-->
~~~~
@@ -533,7 +452,7 @@
}
~~~~
-or placed on the next line indented eight spaces
+or all parameters placed on the next line and indented eight spaces
<!--?prettify?-->
~~~~
