starting next gaggle of docs

starting next gaggle of docs

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

3 files changed, 77 insertions, 21 deletions

diff --git a/tools/bookmaker/bookmaker.cpp b/tools/bookmaker/bookmaker.cpp
index 2ec987b333..4d0c2d9171 100644
--- a/tools/bookmaker/bookmaker.cpp
+++ b/tools/bookmaker/bookmaker.cpp
@@ -10,6 +10,18 @@
 #include "SkOSFile.h"
 #include "SkOSPath.h"
 
+DEFINE_string2(bmh, b, "", "Path to a *.bmh file or a directory.");
+DEFINE_string2(examples, e, "", "File of fiddlecli input, usually fiddle.json (For now, disables -r -f -s)");
+DEFINE_string2(fiddle, f, "", "File of fiddlecli output, usually fiddleout.json.");
+DEFINE_string2(include, i, "", "Path to a *.h file or a directory.");
+DEFINE_bool2(hack, k, false, "Do a find/replace hack to update all *.bmh files. (Requires -b)");
+DEFINE_bool2(stdout, o, false, "Write file out to standard out.");
+DEFINE_bool2(populate, p, false, "Populate include from bmh. (Requires -b -i)");
+DEFINE_string2(ref, r, "", "Resolve refs and write bmh_*.md files to path. (Requires -b)");
+DEFINE_string2(spellcheck, s, "", "Spell-check [once, all, mispelling]. (Requires -b)");
+DEFINE_string2(tokens, t, "", "Directory to write bmh from include. (Requires -i)");
+DEFINE_bool2(crosscheck, x, false, "Check bmh against includes. (Requires -b -i)");
+DEFINE_bool2(skip, z, false, "Skip missing example error.");
 
 /*  recipe for generating timestamps for existing doxygen comments
 find include/core -type f -name '*.h' -print -exec git blame {} \; > ~/all.blame.txt
@@ -118,6 +130,17 @@ void Definition::setCanonicalFiddle() {
                     SkASSERT('=' == fName[opPos + 1]);
                     result += "equal_operator"; 
                 }
+            } else if ('[' == fName[opPos]) {
+                result += "subscript_operator";
+                const char* end = fContentStart;
+                while (end > fStart && ' ' >= end[-1]) {
+                    --end;
+                }
+                string constCheck(fStart, end - fStart);
+                size_t constPos = constCheck.rfind("const");
+                if (constCheck.length() == constPos + 5) {
+                    result += "_const";
+                }
             } else {
                 SkASSERT(0);  // todo: incomplete
             }
@@ -331,7 +354,8 @@ bool Definition::checkMethod() const {
     methodParser.skipName("#Method");
     methodParser.skipSpace();
     string name = this->methodName();
-    if (MethodType::kNone == fMethodType && "()" == name.substr(name.length() - 2)) {
+    if (MethodType::kNone == fMethodType && name.length() > 2 &&
+            "()" == name.substr(name.length() - 2)) {
         name = name.substr(0, name.length() - 2);
     }
     bool expectReturn = this->methodHasReturn(name, &methodParser);
@@ -366,6 +390,9 @@ bool Definition::checkMethod() const {
         string paramName;
         methodParser.fChar = nextEnd + 1;
         methodParser.skipSpace();
+        if (1494 == methodParser.fLineCount) {
+            SkDebugf("");
+        }
         if (!this->nextMethodParam(&methodParser, &nextEnd, &paramName)) {
             continue;
         }
@@ -663,11 +690,29 @@ string Definition::methodName() const {
 
 bool Definition::nextMethodParam(TextParser* methodParser, const char** nextEndPtr, 
         string* paramName) const {
-    *nextEndPtr = methodParser->anyOf(",)");
-    const char* nextEnd = *nextEndPtr;
-    if (!nextEnd) {
-        return methodParser->reportError<bool>("#Method function missing close paren");
+    int parenCount = 0;
+    TextParser::Save saveState(methodParser);
+    while (true) {
+        if (methodParser->eof()) {
+            return methodParser->reportError<bool>("#Method function missing close paren");
+        }
+        char ch = methodParser->peek();
+        if ('(' == ch) {
+            ++parenCount;
+        }
+        if (parenCount == 0 && (')' == ch || ',' == ch)) {
+            *nextEndPtr = methodParser->fChar;
+            break;
+        }
+        if (')' == ch) {
+            if (0 > --parenCount) {
+                return this->reportError<bool>("mismatched parentheses");
+            }
+        }
+        methodParser->next();
     }
+    saveState.restore();
+    const char* nextEnd = *nextEndPtr;
     const char* paramEnd = nextEnd;
     const char* assign = methodParser->strnstr(" = ", paramEnd);
     if (assign) {
@@ -684,6 +729,10 @@ bool Definition::nextMethodParam(TextParser* methodParser, const char** nextEndP
             }
         }
     }
+    const char* function = methodParser->strnstr(")(", paramEnd);
+    if (function) {
+        paramEnd = function;
+    }
     while (paramEnd > methodParser->fChar && ' ' == paramEnd[-1]) {
         --paramEnd;
     }
@@ -1071,7 +1120,9 @@ bool BmhParser::addDefinition(const char* defStart, bool hasEnd, MarkType markTy
                     if (definition->fChildren.size() == 0) {
                         TextParser emptyCheck(definition);
                         if (emptyCheck.eof() || !emptyCheck.skipWhiteSpace()) {
-                            return this->reportError<bool>("missing example body");
+                            if (!FLAGS_skip) {
+                                return this->reportError<bool>("missing example body");
+                            }
                         }
                     }
                 }
@@ -2141,18 +2192,6 @@ string BmhParser::word(const string& prefix, const string& delimiter) {
 // pass one: parse text, collect definitions
 // pass two: lookup references
 
-DEFINE_string2(bmh, b, "", "Path to a *.bmh file or a directory.");
-DEFINE_string2(examples, e, "", "File of fiddlecli input, usually fiddle.json (For now, disables -r -f -s)");
-DEFINE_string2(fiddle, f, "", "File of fiddlecli output, usually fiddleout.json.");
-DEFINE_string2(include, i, "", "Path to a *.h file or a directory.");
-DEFINE_bool2(hack, k, false, "Do a find/replace hack to update all *.bmh files. (Requires -b)");
-DEFINE_bool2(stdout, o, false, "Write file out to standard out.");
-DEFINE_bool2(populate, p, false, "Populate include from bmh. (Requires -b -i)");
-DEFINE_string2(ref, r, "", "Resolve refs and write bmh_*.md files to path. (Requires -b)");
-DEFINE_string2(spellcheck, s, "", "Spell-check [once, all, mispelling]. (Requires -b)");
-DEFINE_string2(tokens, t, "", "Directory to write bmh from include. (Requires -i)");
-DEFINE_bool2(crosscheck, x, false, "Check bmh against includes. (Requires -b -i)");
-
 static int count_children(const Definition& def, MarkType markType) {
     int count = 0;
     if (markType == def.fMarkType) {
diff --git a/tools/bookmaker/mdOut.cpp b/tools/bookmaker/mdOut.cpp
index b0cec6659b..0b0b2e1bca 100644
--- a/tools/bookmaker/mdOut.cpp
+++ b/tools/bookmaker/mdOut.cpp
@@ -14,6 +14,20 @@ static void add_ref(const string& leadingSpaces, const string& ref, string* resu
     *result += leadingSpaces + ref;
 }
 
+static string preformat(const string& orig) {
+    string result;
+    for (auto c : orig) {
+        if ('<' == c) {
+          result += "&lt;";
+        } else if ('>' == c) {
+          result += "&gt;";
+        } else {
+            result += c;
+        }
+    }
+    return result;
+}
+
 // FIXME: preserve inter-line spaces and don't add new ones
 string MdOut::addReferences(const char* refStart, const char* refEnd,
         BmhParser::Resolvable resolvable) {
@@ -149,7 +163,7 @@ string MdOut::addReferences(const char* refStart, const char* refEnd,
                 if (('f' != ref[0] && string::npos == ref.find("()"))
 //                        || '.' != t.backup(ref.c_str())
                         && ('k' != ref[0] && string::npos == ref.find("_Private"))) {
-                    if ('.' == wordStart[0] && distFromParam == 1) {
+                    if ('.' == wordStart[0] && (distFromParam >= 1 && distFromParam <= 16)) {
                         const Definition* paramType = this->findParamType();
                         if (paramType) {
                             string fullName = paramType->fName + "::" + ref;
@@ -756,10 +770,11 @@ void MdOut::markTypeOut(Definition* def) {
             // TODO: put in css spec that we can define somewhere else (if markup supports that)
             // TODO: 50em below should match limt = 80 in formatFunction()
             this->writePending();
+            string preformattedStr = preformat(formattedStr);
             fprintf(fOut, "<pre style=\"padding: 1em 1em 1em 1em;"
                                     "width: 50em; background-color: #f0f0f0\">\n"
                             "%s\n"
-                            "</pre>",  formattedStr.c_str());
+                            "</pre>",  preformattedStr.c_str());
             this->lf(2);
             fTableState = TableState::kNone;
             fMethod = def;
diff --git a/tools/bookmaker/spellCheck.cpp b/tools/bookmaker/spellCheck.cpp
index 7a45fb04ed..eb430f877c 100644
--- a/tools/bookmaker/spellCheck.cpp
+++ b/tools/bookmaker/spellCheck.cpp
@@ -579,7 +579,8 @@ void SpellCheck::wordCheck(const string& str) {
         hasColon |= isColon;
         bool isDot = '.' == ch;
         hasDot |= isDot;
-        bool isParen = '(' == ch || ')' == ch || '~' == ch || '=' == ch || '!' == ch;
+        bool isParen = '(' == ch || ')' == ch || '~' == ch || '=' == ch || '!' == ch ||
+                '[' == ch || ']' == ch;
         hasParen |= isParen;
         bool isUnderscore = '_' == ch;
         hasUnderscore |= isUnderscore;
@@ -594,6 +595,7 @@ void SpellCheck::wordCheck(const string& str) {
             sawSpecial = true;
             continue;
         }
+        SkDebugf("");
         SkASSERT(0);
     }
     if (sawSpecial && !hasParen) {