support srgb flag in bookmaker

allow examples to work with colorspace
fix point array plural form
fix spacing after private message
add some SkImage documentation

TBR=caryclark@google.com
Docs-Preview: https://skia.org/?cl=90360
Bug: skia:6898
Change-Id: I045ee68e7dd9747ec5d40d95588bbc1594c45366
Reviewed-on: https://skia-review.googlesource.com/90360
Reviewed-by: Cary Clark <caryclark@skia.org>
Commit-Queue: Cary Clark <caryclark@skia.org>

6 files changed, 34 insertions, 3 deletions

diff --git a/tools/bookmaker/bookmaker.cpp b/tools/bookmaker/bookmaker.cpp
index 2677621ee1..b7aa044885 100644
--- a/tools/bookmaker/bookmaker.cpp
+++ b/tools/bookmaker/bookmaker.cpp
@@ -342,6 +342,7 @@ bool BmhParser::addDefinition(const char* defStart, bool hasEnd, MarkType markTy
         case MarkType::kOutdent:
         case MarkType::kPlatform:
         case MarkType::kSeeAlso:
+        case MarkType::kSet:
         case MarkType::kSubstitute:
         case MarkType::kTime:
         case MarkType::kVolatile:
@@ -1262,6 +1263,7 @@ vector<string> BmhParser::typeName(MarkType markType, bool* checkEnd) {
         case MarkType::kPlatform:
         case MarkType::kReturn:
         case MarkType::kSeeAlso:
+        case MarkType::kSet:
         case MarkType::kSubstitute:
         case MarkType::kTime:
         case MarkType::kToDo:
diff --git a/tools/bookmaker/bookmaker.h b/tools/bookmaker/bookmaker.h
index cb0e8dab16..f309d795c9 100644
--- a/tools/bookmaker/bookmaker.h
+++ b/tools/bookmaker/bookmaker.h
@@ -122,6 +122,7 @@ enum class MarkType {
     kRoot,
     kRow,
     kSeeAlso,
+    kSet,
     kStdOut,
     kStruct,
     kSubstitute,
@@ -1236,6 +1237,7 @@ public:
 , { "",            nullptr,      MarkType::kRow,          R_Y, E_N, M(Table) | M(List) }
 , { "SeeAlso",     nullptr,      MarkType::kSeeAlso,      R_Y, E_N,
                                                              M_CSST | M_E | M(Method) | M(Typedef) }
+, { "Set",         nullptr,      MarkType::kSet,          R_N, E_N, M(Example) }
 , { "StdOut",      nullptr,      MarkType::kStdOut,       R_N, E_N, M(Example) }
 , { "Struct",      &fClassMap,   MarkType::kStruct,       R_Y, E_O, M(Class) | M(Root) | M_ST }
 , { "Substitute",  nullptr,      MarkType::kSubstitute,   R_N, E_N, M_ST }
@@ -1425,6 +1427,7 @@ public:
         , { nullptr,        MarkType::kRoot }
         , { nullptr,        MarkType::kRow }
         , { nullptr,        MarkType::kSeeAlso }
+        , { nullptr,        MarkType::kSet }
         , { nullptr,        MarkType::kStdOut }
         , { &fIStructMap,   MarkType::kStruct }
         , { nullptr,        MarkType::kSubstitute }
diff --git a/tools/bookmaker/definition.cpp b/tools/bookmaker/definition.cpp
index 933ecc6868..77f4446445 100644
--- a/tools/bookmaker/definition.cpp
+++ b/tools/bookmaker/definition.cpp
@@ -526,6 +526,7 @@ bool Definition::exampleToScript(string* result, ExampleOptions exampleOptions)
     string normalizedName(fFiddle);
     string code;
     string imageStr = "0";
+    string srgbStr = "false";
     for (auto const& iter : fChildren) {
         switch (iter->fMarkType) {
             case MarkType::kError:
@@ -562,6 +563,15 @@ bool Definition::exampleToScript(string* result, ExampleOptions exampleOptions)
             case MarkType::kPlatform:
                 // ignore for now
                 break;
+            case MarkType::kSet:
+                if ("sRGB" == string(iter->fContentStart,
+                                     iter->fContentEnd - iter->fContentStart)) {
+                    srgbStr = "true";
+                } else {
+                    SkASSERT(0);   // more work to do
+                    return false;
+                }
+                break;
             case MarkType::kStdOut:
                 textOut = true;
                 break;
@@ -609,7 +619,7 @@ bool Definition::exampleToScript(string* result, ExampleOptions exampleOptions)
             example += "        \"width\": " + widthStr + ",\n";
             example += "        \"height\": " + heightStr + ",\n";
             example += "        \"source\": " + imageStr + ",\n";
-            example += "        \"srgb\": false,\n";
+            example += "        \"srgb\": " + srgbStr + ",\n";
             example += "        \"f16\": false,\n";
             example += "        \"textOnly\": " + textOutStr + ",\n";
             example += "        \"animated\": false,\n";
diff --git a/tools/bookmaker/includeParser.cpp b/tools/bookmaker/includeParser.cpp
index da2ee54c2e..363aacc650 100644
--- a/tools/bookmaker/includeParser.cpp
+++ b/tools/bookmaker/includeParser.cpp
@@ -1493,6 +1493,9 @@ bool IncludeParser::parseMethod(Definition* child, Definition* markupDef) {
     }
     tokenIter->fName = nameStr;
     tokenIter->fMarkType = MarkType::kMethod;
+    if (string::npos != nameStr.find("defined")) {
+        SkDebugf("");
+    }
     tokenIter->fPrivate = string::npos != nameStr.find("::");
     auto testIter = child->fParent->fTokens.begin();
     SkASSERT(child->fParentIndex > 0);
@@ -1642,10 +1645,18 @@ bool IncludeParser::parseObject(Definition* child, Definition* markupDef) {
                         auto tokenIter = child->fParent->fTokens.begin();
                         std::advance(tokenIter, child->fParentIndex);
                         tokenIter = std::prev(tokenIter);
-                        TextParser checkDeprecated(&*tokenIter);
-                        if (checkDeprecated.startsWith("SK_ATTR_DEPRECATED")) {
+                        TextParser previousToken(&*tokenIter);
+                        if (previousToken.startsWith("SK_ATTR_DEPRECATED")) {
                             break;
                         }
+                        if (Bracket::kPound == child->fParent->fBracket &&
+                                KeyWord::kIf == child->fParent->fKeyWord) {
+                            // TODO: this will skip methods named defined() -- for the
+                            // moment there aren't any
+                            if (previousToken.startsWith("defined")) {
+                                break;
+                            }
+                        }
                     }
                     if (!this->parseMethod(child, markupDef)) {
                         return child->reportError<bool>("failed to parse method");
diff --git a/tools/bookmaker/includeWriter.cpp b/tools/bookmaker/includeWriter.cpp
index e8d86f0916..c34fc9391f 100644
--- a/tools/bookmaker/includeWriter.cpp
+++ b/tools/bookmaker/includeWriter.cpp
@@ -65,6 +65,9 @@ void IncludeWriter::descriptionOut(const Definition* def) {
                 commentLen = (int) (prop->fContentEnd - commentStart);
                 if (commentLen > 0) {
                     this->writeBlockIndent(commentLen, commentStart);
+                    if ('\n' != commentStart[commentLen - 1] && '\n' == commentStart[commentLen]) {
+                        this->lfcr();
+                    }
                 }
                 commentStart = prop->fTerminator;
                 commentLen = (int) (def->fContentEnd - commentStart);
diff --git a/tools/bookmaker/mdOut.cpp b/tools/bookmaker/mdOut.cpp
index 0153e49e95..d6069e4b3a 100644
--- a/tools/bookmaker/mdOut.cpp
+++ b/tools/bookmaker/mdOut.cpp
@@ -883,6 +883,8 @@ void MdOut::markTypeOut(Definition* def) {
             fprintf(fOut, "See Also");
             this->lf(2);
             break;
+        case MarkType::kSet:
+            break;
         case MarkType::kStdOut: {
             TextParser code(def);
             this->mdHeaderOut(4);