fix bugs exposed by documenting SkImageInfo

- More rigorous symbol identification creates additional
links, and finds spurious errors like unnecessary
parentheses.

- Fixed code to allow preprocessor directives in
#Code blocks (still more to do).

- Fixed examples waiting on fiddle updates.

- Make SkImageInfo officially documented (update in status.json).

- Fixed enum indentation.



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

1 files changed, 75 insertions, 60 deletions

diff --git a/tools/bookmaker/mdOut.cpp b/tools/bookmaker/mdOut.cpp
index 80d3e21faa..4b4e2b89be 100644
--- a/tools/bookmaker/mdOut.cpp
+++ b/tools/bookmaker/mdOut.cpp
@@ -93,8 +93,7 @@ string MdOut::addReferences(const char* refStart, const char* refEnd,
             continue;
         }
         ref = string(start, t.fChar - start);
-        if (const Definition* def = this->isDefined(t, ref,
-                BmhParser::Resolvable::kOut != resolvable)) {
+        if (const Definition* def = this->isDefined(t, ref, resolvable)) {
             if (MarkType::kExternal == def->fMarkType) {
                 add_ref(leadingSpaces, ref, &result);
                 continue;
@@ -122,7 +121,7 @@ string MdOut::addReferences(const char* refStart, const char* refEnd,
                     }
                     string altTest = ref + '_';
                     altTest += suffix++;
-                    altDef = this->isDefined(t, altTest, false);
+                    altDef = this->isDefined(t, altTest, BmhParser::Resolvable::kOut);
                 }
                 if (suffix > '9') {
                     t.reportError("too many alts");
@@ -130,13 +129,18 @@ string MdOut::addReferences(const char* refStart, const char* refEnd,
                     return result;
                 }
                 if (!foundMatch) {
-                    if (!(def = this->isDefined(t, fullRef,
-                            BmhParser::Resolvable::kOut != resolvable))) {
-                        if (!result.size()) {
+                    if (!(def = this->isDefined(t, fullRef, resolvable))) {
+                        if (BmhParser::Resolvable::kFormula == resolvable) {
+                            // TODO: look for looser mapping -- if methods name match, look for
+                            //   unique mapping based on number of parameters
+                            // for now, just look for function name match
+                            def = this->isDefined(t, ref, resolvable);
+                        }
+                        if (!def && !result.size()) {
                             t.reportError("missing method");
                             fAddRefFailed = true;
+                            return result;
                         }
-                        return result;
                     }
                     ref = fullRef;
                 }
@@ -145,6 +149,11 @@ string MdOut::addReferences(const char* refStart, const char* refEnd,
 				add_ref(leadingSpaces, ref, &result);
 				continue;
 			}
+            if (!def) {
+                t.reportError("missing method");
+                fAddRefFailed = true;
+                return result;
+            }
 			result += linkRef(leadingSpaces, def, ref, resolvable);
             continue;
         }
@@ -156,7 +165,7 @@ string MdOut::addReferences(const char* refStart, const char* refEnd,
             }
             t.next();
             ref = string(start, t.fChar - start);
-            if (const Definition* def = this->isDefined(t, ref, true)) {
+            if (const Definition* def = this->isDefined(t, ref, BmhParser::Resolvable::kYes)) {
                 SkASSERT(def->fFiddle.length());
 				result += linkRef(leadingSpaces, def, ref, resolvable);
                 continue;
@@ -173,15 +182,15 @@ string MdOut::addReferences(const char* refStart, const char* refEnd,
             if (BmhParser::Resolvable::kOut != resolvable) {
                 t.reportError("missed Sk prefixed");
                 fAddRefFailed = true;
+                return result;
             }
-            return result;
         }
         if (!ref.compare(0, 2, "SK")) {
             if (BmhParser::Resolvable::kOut != resolvable) {
                 t.reportError("missed SK prefixed");
                 fAddRefFailed = true;
+                return result;
             }
-            return result;
         }
         if (!isupper(start[0])) {
             // TODO:
@@ -209,7 +218,8 @@ string MdOut::addReferences(const char* refStart, const char* refEnd,
                             }
                         }
                     }
-                    if (BmhParser::Resolvable::kOut != resolvable) {
+                    if (BmhParser::Resolvable::kOut != resolvable &&
+                            BmhParser::Resolvable::kFormula != resolvable) {
                         t.reportError("missed camelCase");
                         fAddRefFailed = true;
                         return result;
@@ -236,7 +246,7 @@ string MdOut::addReferences(const char* refStart, const char* refEnd,
         if (isupper(t.fChar[1]) && startsSentence) {
             TextParser next(t.fFileName, &t.fChar[1], t.fEnd, t.fLineCount);
             string nextWord(next.fChar, next.wordEnd() - next.fChar);
-            if (this->isDefined(t, nextWord, true)) {
+            if (this->isDefined(t, nextWord, BmhParser::Resolvable::kYes)) {
 				add_ref(leadingSpaces, ref, &result);
                 continue;
             }
@@ -261,6 +271,8 @@ string MdOut::addReferences(const char* refStart, const char* refEnd,
             if (BmhParser::Resolvable::kOut != resolvable) {
                 t.reportError("undefined reference");
                 fAddRefFailed = true;
+            } else {
+				add_ref(leadingSpaces, ref, &result);
             }
         }
     } while (!t.eof());
@@ -269,25 +281,22 @@ string MdOut::addReferences(const char* refStart, const char* refEnd,
 
 
 
-bool MdOut::buildReferences(const char* docDir, const char* mdFileOrPath) {
+bool MdOut::buildReferences(const IncludeParser& includeParser, const char* docDir,
+        const char* mdFileOrPath) {
     if (!sk_isdir(mdFileOrPath)) {
-        SkString mdFile = SkOSPath::Basename(mdFileOrPath);
-        SkString bmhFile = SkOSPath::Join(docDir, mdFile.c_str());
-        bmhFile.remove(bmhFile.size() - 3, 3);
-        bmhFile += ".bmh";
-        SkString mdPath = SkOSPath::Dirname(mdFileOrPath);
-        if (!this->buildRefFromFile(bmhFile.c_str(), mdPath.c_str())) {
-            SkDebugf("failed to parse %s\n", mdFileOrPath);
-            return false;
+        SkDebugf("must pass directory %s\n", mdFileOrPath);
+        SkDebugf("pass -i SkXXX.h to build references for a single include\n");
+        return false;
+    }
+    SkOSFile::Iter it(docDir, ".bmh");
+    for (SkString file; it.next(&file); ) {
+        if (!includeParser.references(file)) {
+            continue;
         }
-    } else {
-        SkOSFile::Iter it(docDir, ".bmh");
-        for (SkString file; it.next(&file); ) {
-            SkString p = SkOSPath::Join(docDir, file.c_str());
-            if (!this->buildRefFromFile(p.c_str(), mdFileOrPath)) {
-                SkDebugf("failed to parse %s\n", p.c_str());
-                return false;
-            }
+        SkString p = SkOSPath::Join(docDir, file.c_str());
+        if (!this->buildRefFromFile(p.c_str(), mdFileOrPath)) {
+            SkDebugf("failed to parse %s\n", p.c_str());
+            return false;
         }
     }
     return true;
@@ -409,7 +418,7 @@ bool MdOut::checkParamReturnBody(const Definition* def) {
     if (!islower(descriptionStart[0]) && !isdigit(descriptionStart[0])) {
         paramBody.skipToNonAlphaNum();
         string ref = string(descriptionStart, paramBody.fChar - descriptionStart);
-        if (!this->isDefined(paramBody, ref, true)) {
+        if (!this->isDefined(paramBody, ref, BmhParser::Resolvable::kYes)) {
             string errorStr = MarkType::kReturn == def->fMarkType ? "return" : "param";
             errorStr += " description must start with lower case";
             paramBody.reportError(errorStr.c_str());
@@ -484,7 +493,8 @@ const Definition* MdOut::findParamType() {
         SkASSERT(!parser.eof());
         string name = string(word, parser.fChar - word);
         if (fLastParam->fName == name) {
-            const Definition* paramType = this->isDefined(parser, lastFull, false);
+            const Definition* paramType = this->isDefined(parser, lastFull,
+                    BmhParser::Resolvable::kOut);
             return paramType;
         }
         if (isupper(name[0])) {
@@ -494,7 +504,8 @@ const Definition* MdOut::findParamType() {
     return nullptr;
 }
 
-const Definition* MdOut::isDefined(const TextParser& parser, const string& ref, bool report) {
+const Definition* MdOut::isDefined(const TextParser& parser, const string& ref,
+        BmhParser::Resolvable resolvable) {
     auto rootIter = fBmhParser.fClassMap.find(ref);
     if (rootIter != fBmhParser.fClassMap.end()) {
         return &rootIter->second;
@@ -613,7 +624,8 @@ const Definition* MdOut::isDefined(const TextParser& parser, const string& ref,
                 return nullptr;
             }
         } else {
-            if (report) {
+            if (BmhParser::Resolvable::kOut != resolvable &&
+                    BmhParser::Resolvable::kFormula != resolvable) {
                 parser.reportError("SK undefined");
                 fAddRefFailed = true;
             }
@@ -643,7 +655,8 @@ const Definition* MdOut::isDefined(const TextParser& parser, const string& ref,
                     return definition;
                 }
             }
-            if (report) {
+            if (BmhParser::Resolvable::kOut != resolvable &&
+                    BmhParser::Resolvable::kFormula != resolvable) {
                 parser.reportError("_ undefined");
                 fAddRefFailed = true;
             }
@@ -797,6 +810,7 @@ void MdOut::markTypeOut(Definition* def) {
             FPRINTF("<pre style=\"padding: 1em 1em 1em 1em;"
                     "width: 62.5em; background-color: #f0f0f0\">");
             this->lf(1);
+            fResolveAndIndent = true;
             break;
         case MarkType::kColumn:
             this->writePending();
@@ -889,7 +903,7 @@ void MdOut::markTypeOut(Definition* def) {
                 if (def->fWrapper.length() > 0) {
                     FPRINTF("%s", def->fWrapper.c_str());
                 }
-                fRespectLeadingSpace = true;
+                fLiteralAndIndent = true;
             }
             } break;
         case MarkType::kExperimental:
@@ -1107,7 +1121,8 @@ void MdOut::markTypeOut(Definition* def) {
         case MarkType::kWidth:
             break;
         case MarkType::kPhraseDef:
-            break;
+            // skip text and children
+            return;
         case MarkType::kPhraseRef:
             if (fBmhParser.fPhraseMap.end() == fBmhParser.fPhraseMap.find(def->fName)) {
                 def->reportError<void>("missing phrase definition");
@@ -1139,9 +1154,12 @@ void MdOut::markTypeOut(Definition* def) {
             }
             break;
         case MarkType::kCode:
+            fIndent = 0;
+            this->lf(1);
             this->writePending();
             FPRINTF("</pre>");
             this->lf(2);
+            fResolveAndIndent = false;
             break;
         case MarkType::kColumn:
             if (fInList) {
@@ -1174,7 +1192,7 @@ void MdOut::markTypeOut(Definition* def) {
                 FPRINTF("</pre>");
             }
             this->lf(2);
-            fRespectLeadingSpace = false;
+            fLiteralAndIndent = false;
             break;
         case MarkType::kLink:
             this->writeString("</a>");
@@ -1317,10 +1335,16 @@ void MdOut::populateTables(const Definition* def) {
 }
 
 void MdOut::resolveOut(const char* start, const char* end, BmhParser::Resolvable resolvable) {
-    if ((BmhParser::Resolvable::kLiteral == resolvable || fRespectLeadingSpace) && end > start) {
+    if ((BmhParser::Resolvable::kLiteral == resolvable || fLiteralAndIndent ||
+            fResolveAndIndent) && end > start) {
+        int linefeeds = 0;
         while ('\n' == *start) {
+            ++linefeeds;
             ++start;
         }
+        if (fResolveAndIndent && linefeeds) {
+            this->lf(linefeeds);
+        }
         const char* spaceStart = start;
         while (' ' == *start) {
             ++start;
@@ -1328,6 +1352,8 @@ void MdOut::resolveOut(const char* start, const char* end, BmhParser::Resolvable
         if (start > spaceStart) {
             fIndent = start - spaceStart;
         }
+    }
+    if (BmhParser::Resolvable::kLiteral == resolvable || fLiteralAndIndent) {
         this->writeBlockTrim(end - start, start);
         if ('\n' == end[-1]) {
             this->lf(1);
@@ -1347,14 +1373,20 @@ void MdOut::resolveOut(const char* start, const char* end, BmhParser::Resolvable
     trim_end_spaces(resolved);
     if (resolved.length()) {
         TextParser paragraph(fFileName, &*resolved.begin(), &*resolved.end(), fLineCount);
-        TextParser original(fFileName, start, end, fLineCount);
-        while (!original.eof() && '\n' == original.peek()) {
-            original.next();
-        }
-        original.skipSpace();
         while (!paragraph.eof()) {
+            while ('\n' == paragraph.peek()) {
+                paragraph.next();
+                if (paragraph.eof()) {
+                    return;
+                }
+            }
+            const char* lineStart = paragraph.fChar;
             paragraph.skipWhiteSpace();
             const char* contentStart = paragraph.fChar;
+            if (fResolveAndIndent && contentStart > lineStart) {
+                this->writePending();
+                this->indentToColumn(contentStart - lineStart);
+            }
             paragraph.skipToEndBracket('\n');
             ptrdiff_t lineLength = paragraph.fChar - contentStart;
             if (lineLength) {
@@ -1364,17 +1396,6 @@ void MdOut::resolveOut(const char* start, const char* end, BmhParser::Resolvable
                 string str(contentStart, lineLength);
                 this->writeString(str.c_str());
             }
-#if 0
-            int linefeeds = 0;
-            while (lineLength > 0 && '\n' == contentStart[--lineLength]) {
-
-                ++linefeeds;
-            }
-            if (lineLength > 0) {
-                this->nl();
-            }
-            fLinefeeds += linefeeds;
-#endif
             if (paragraph.eof()) {
                 break;
             }
@@ -1386,12 +1407,6 @@ void MdOut::resolveOut(const char* start, const char* end, BmhParser::Resolvable
                 this->lf(linefeeds);
             }
         }
-#if 0
-        while (end > start && end[0] == '\n') {
-            FPRINTF("\n");
-            --end;
-        }
-#endif
     }
 }