auto table generation

Replace manually entered summary tables with ones that are populated
and sorted by bookmaker. This introduces a slight regression for
anonymous enums but fixes a lot of bugs and omissions.

The format is

#Topic somethingTopical
#Populate
##

where somethingTopical is one of Subtopics, Constructors, Constants,
Classes_and_Structs, Members, Member_Functions, and Related_Functions.

Fix the bad formatting in SkCanvas reference. The #Error tag was
was corrupting the markdown table. Remove the tag and replace it
with #NoExample.

Next up: revise self-check to know about populated topics.

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

1 files changed, 153 insertions, 34 deletions

diff --git a/tools/bookmaker/mdOut.cpp b/tools/bookmaker/mdOut.cpp
index 995491d136..b51bb8d77e 100644
--- a/tools/bookmaker/mdOut.cpp
+++ b/tools/bookmaker/mdOut.cpp
@@ -232,13 +232,13 @@ string MdOut::addReferences(const char* refStart, const char* refEnd,
                 continue;
             }
         }
-        Definition* test = fRoot;
+        const Definition* test = fRoot;
         do {
             if (!test->isRoot()) {
                 continue;
             }
             for (string prefix : { "_", "::" } ) {
-                RootDefinition* root = test->asRoot();
+                const RootDefinition* root = test->asRoot();
                 string prefixed = root->fName + prefix + ref;
                 if (const Definition* def = root->find(prefixed,
                         RootDefinition::AllowParens::kYes)) {
@@ -357,6 +357,15 @@ bool MdOut::buildRefFromFile(const char* name, const char* outDir) {
             this->lfAlways(1);
             FPRINTF("===");
         }
+        fPopulators[kClassesAndStructs].fDescription = "embedded struct and class members";
+        fPopulators[kConstants].fDescription = "enum and enum class, const values";
+        fPopulators[kConstructors].fDescription = "functions that construct";
+        fPopulators[kMemberFunctions].fDescription = "static functions and member methods";
+        fPopulators[kMembers].fDescription = "member values";
+        fPopulators[kOperators].fDescription = "operator overloading methods";
+        fPopulators[kRelatedFunctions].fDescription = "similar methods grouped together";
+        fPopulators[kSubtopics].fDescription = "";
+        this->populateTables(fRoot);
         this->markTypeOut(topicDef);
     }
     if (fOut) {
@@ -424,6 +433,24 @@ void MdOut::childrenOut(const Definition* def, const char* start) {
     }
 }
 
+const Definition* MdOut::csParent() const {
+    const Definition* csParent = fRoot->csParent();
+    if (!csParent) {
+        const Definition* topic = fRoot;
+        while (topic && MarkType::kTopic != topic->fMarkType) {
+            topic = topic->fParent;
+        }
+        for (auto child : topic->fChildren) {
+            if (child->isStructOrClass() || MarkType::kTypedef == child->fMarkType) {
+                csParent = child;
+                break;
+            }
+        }
+        SkASSERT(csParent || string::npos == fRoot->fFileName.find("Sk"));
+    }
+    return csParent;
+}
+
 const Definition* MdOut::findParamType() {
     SkASSERT(fMethod);
     TextParser parser(fMethod->fFileName, fMethod->fStart, fMethod->fContentStart,
@@ -486,12 +513,12 @@ const Definition* MdOut::isDefined(const TextParser& parser, const string& ref,
         if (const Definition* definition = fRoot->find(ref, RootDefinition::AllowParens::kYes)) {
             return definition;
         }
-        Definition* test = fRoot;
+        const Definition* test = fRoot;
         do {
             if (!test->isRoot()) {
                 continue;
             }
-            RootDefinition* root = test->asRoot();
+            const RootDefinition* root = test->asRoot();
             for (auto& leaf : root->fBranches) {
                 if (ref == leaf.first) {
                     return leaf.second;
@@ -626,7 +653,7 @@ string MdOut::linkRef(const string& leadingSpaces, const Definition* def,
     const string* str = &def->fFiddle;
     SkASSERT(str->length() > 0);
     size_t under = str->find('_');
-    Definition* curRoot = fRoot;
+    const Definition* curRoot = fRoot;
     string classPart = string::npos != under ? str->substr(0, under) : *str;
     bool classMatch = curRoot->fName == classPart;
     while (curRoot->fParent) {
@@ -798,8 +825,6 @@ void MdOut::markTypeOut(Definition* def) {
             FPRINTF("<a name=\"%s\"></a> Enum %s", def->fFiddle.c_str(), def->fName.c_str());
             this->lf(2);
             break;
-        case MarkType::kError:
-            break;
         case MarkType::kExample: {
             this->mdHeaderOut(3);
             FPRINTF("Example\n"
@@ -816,7 +841,7 @@ void MdOut::markTypeOut(Definition* def) {
                     gpuAndCpu = platParse.strnstr("cpu", platParse.fEnd);
                 }
             }
-            if (fHasFiddle && !def->hasChild(MarkType::kError)) {
+            if (fHasFiddle) {
                 SkASSERT(def->fHash.length() > 0);
                 FPRINTF("<div><fiddle-embed name=\"%s\"", def->fHash.c_str());
                 if (showGpu) {
@@ -944,6 +969,18 @@ void MdOut::markTypeOut(Definition* def) {
         } break;
         case MarkType::kPlatform:
             break;
+        case MarkType::kPopulate: {
+            SkASSERT(MarkType::kSubtopic == def->fParent->fMarkType);
+            string name = def->fParent->fName;
+            if (kSubtopics == name) {
+                this->subtopicsOut();
+            } else {
+                SkASSERT(kClassesAndStructs == name || kConstants == name || kConstructors == name
+                        || kMemberFunctions == name || kMembers == name || kOperators == name
+                        || kRelatedFunctions == name);
+                this->subtopicOut(this->populator(name.c_str()));
+            }
+            } break;
         case MarkType::kPrivate:
             break;
         case MarkType::kReturn:
@@ -1147,32 +1184,55 @@ void MdOut::mdHeaderOutLF(int depth, int lf) {
     FPRINTF(" ");
 }
 
-void MdOut::overviewOut() {
-#if 0  // under development
-    // substitute $1 with def (e.g. Subtopics); substitute $2 with ref (e.g. SkRect)
-    const char header[] =
-            "## $1\n"
-            "\n"
-            "| name | description |\n"
-            "| --- | ---  |\n";
-    const char* topics[] = {
-            "Classes_and_Structs", "embedded struct and class members",
-            "Constants",           "enum and enum class, const values",
-            "Constructors",        "functions that construct $2",
-            "Member_Function",     "static functions and member methods",
-            "Members",             "member values",
-            "Operator",            "operator overloading methods",
-            "Related_Functions",  "similar methods grouped together",
-    };
-    int found = 0;
-    vector<Definition*> classesAndStructs;
-    vector<Definition*> constants;
-    vector<Definition*> constructors;
-    vector<Definition*> memberFunctions;
-    vector<Definition*> members;
-    vector<Definition*> operators;
-    vector<Definition*> relatedFunctions;
-#endif
+void MdOut::populateTables(const Definition* def) {
+    const Definition* csParent = this->csParent();
+    for (auto child : def->fChildren) {
+        if (MarkType::kTopic == child->fMarkType || MarkType::kSubtopic == child->fMarkType) {
+            bool legacyTopic = fPopulators.end() != fPopulators.find(child->fName);
+            if (!legacyTopic && child->fName != kOverview) {
+                this->populator(kRelatedFunctions).push_back(child);
+            }
+            this->populateTables(child);
+            continue;
+        }
+        if (child->isStructOrClass()) {
+            if (fClassStack.size() > 0) {
+                this->populator(kClassesAndStructs).push_back(child);
+            }
+            fClassStack.push_back(child);
+            this->populateTables(child);
+            fClassStack.pop_back();
+            continue;
+        }
+        if (MarkType::kEnum == child->fMarkType || MarkType::kEnumClass == child->fMarkType) {
+            this->populator(kConstants).push_back(child);
+            continue;
+        }
+        if (MarkType::kMember == child->fMarkType) {
+            this->populator(kMembers).push_back(child);
+            continue;
+        }
+        if (MarkType::kMethod != child->fMarkType) {
+            continue;
+        }
+        if (child->fClone) {
+            continue;
+        }
+        if (Definition::MethodType::kConstructor == child->fMethodType
+                || Definition::MethodType::kDestructor == child->fMethodType) {
+            this->populator(kConstructors).push_back(child);
+            continue;
+        }
+        if (Definition::MethodType::kOperator == child->fMethodType) {
+            this->populator(kOperators).push_back(child);
+            continue;
+        }
+        this->populator(kMemberFunctions).push_back(child);
+        if (csParent && (0 == child->fName.find(csParent->fName + "::Make")
+                || 0 == child->fName.find(csParent->fName + "::make"))) {
+            this->populator(kConstructors).push_back(child);
+        }
+    }
 }
 
 void MdOut::resolveOut(const char* start, const char* end, BmhParser::Resolvable resolvable) {
@@ -1253,3 +1313,62 @@ void MdOut::resolveOut(const char* start, const char* end, BmhParser::Resolvable
 #endif
     }
 }
+
+void MdOut::rowOut(const char* name, const string& description) {
+    this->lfAlways(1);
+    FPRINTF("| ");
+    this->resolveOut(name, name + strlen(name), BmhParser::Resolvable::kYes);
+    FPRINTF(" | ");
+    this->resolveOut(&description.front(), &description.back() + 1, BmhParser::Resolvable::kYes);
+    FPRINTF(" |");
+    this->lf(1);
+}
+
+void MdOut::subtopicsOut() {
+    const Definition* csParent = this->csParent();
+    SkASSERT(csParent);
+    this->rowOut("name", "description");
+    this->rowOut("---", "---");
+    for (auto item : { kClassesAndStructs, kConstants, kConstructors, kMemberFunctions,
+            kMembers, kOperators, kRelatedFunctions } ) {
+        for (auto entry : this->populator(item)) {
+            if (entry->csParent() == csParent) {
+                string description = fPopulators.find(item)->second.fDescription;
+                if (kConstructors == item) {
+                    description += " " + csParent->fName;
+                }
+                this->rowOut(item, description);
+                break;
+            }
+        }
+    }
+}
+
+void MdOut::subtopicOut(vector<const Definition*>& data) {
+    const Definition* csParent = this->csParent();
+    SkASSERT(csParent);
+    fRoot = csParent->asRoot();
+    this->rowOut("name", "description");
+    this->rowOut("---", "---");
+    std::map<string, const Definition*> items;
+    for (auto entry : data) {
+        if (entry->csParent() != csParent) {
+            continue;
+        }
+        size_t start = entry->fName.find_last_of("::");
+        string name = entry->fName.substr(string::npos == start ? 0 : start + 1);
+        items[name] = entry;
+    }
+    for (auto entry : items) {
+        const Definition* oneLiner = nullptr;
+        for (auto child : entry.second->fChildren) {
+            if (MarkType::kLine == child->fMarkType) {
+                oneLiner = child;
+                break;
+            }
+        }
+        SkASSERT(oneLiner);
+        this->rowOut(entry.first.c_str(), string(oneLiner->fContentStart,
+            oneLiner->fContentEnd - oneLiner->fContentStart));
+    }
+}