working on global enum and image info

Added global enum support. That exposed one
big hole in bookmaker: The topic overview
should not be in the class or struct if
the topic includes multiple objects, which
is the case for SkImageInfo and enums like
SkColorType.

This straightens that out, and then used that
knowledge to strengthen the topics in
SkRect as a test. Now SkRect has more
groups of methods, and can expose and link
to sets of methods with the same name.

This work also is getting ready for tightening
SeeAlso data, to be checked as part of the
bots' tasks soon.

Also, remove links from markup for lowercase
method names unless the reference has
trailing parentheses.

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

1 files changed, 83 insertions, 88 deletions

diff --git a/tools/bookmaker/selfCheck.cpp b/tools/bookmaker/selfCheck.cpp
index 7f112697c0..16db3da9bd 100644
--- a/tools/bookmaker/selfCheck.cpp
+++ b/tools/bookmaker/selfCheck.cpp
@@ -67,18 +67,8 @@ protected:
                 continue;
             }
             auto& cs = rootChild;
-            auto overview = this->findOverview(cs);
-            if (!overview) {
-                return false;
-            }
-            Definition* constructors = nullptr;
-            for (auto& overChild : overview->fChildren) {
-                if ("Constructors" == overChild->fName) {
-                    constructors = overChild;
-                    break;
-                }
-            }
-            if (constructors && MarkType::kSubtopic != constructors->fMarkType) {
+			auto constructors = this->findTopic("Constructors", Optional::kYes);
+			if (constructors && MarkType::kSubtopic != constructors->fMarkType) {
                 return constructors->reportError<bool>("expected #Subtopic Constructors");
             }
             vector<string> constructorEntries;
@@ -141,56 +131,47 @@ protected:
     // Check that summary contains all methods
     bool checkMethodSummary() {
         // look for struct or class in fChildren
-        for (auto& rootChild : fRoot->fChildren) {
-            if (!this->isStructOrClass(rootChild)) {
+		Definition* cs = nullptr;
+		for (auto& rootChild : fRoot->fChildren) {
+			if (!this->isStructOrClass(rootChild)) {
+				continue;
+			}
+			cs = rootChild;
+			// expect Overview as Topic in every main class or struct or its parent
+		}
+		if (!cs) {
+			return true;  // topics may not have included classes or structs
+		}
+		auto memberFunctions = this->findTopic("Member_Functions", Optional::kNo);
+        if (MarkType::kSubtopic != memberFunctions->fMarkType) {
+            return memberFunctions->reportError<bool>("expected #Subtopic Member_Functions");
+        }
+        vector<string> methodEntries; // build map of overview entries
+        if (!this->collectEntries(memberFunctions, &methodEntries)) {
+            return false;
+        }
+        // mark corresponding methods as visited (may be more than one per entry)
+        for (auto& csChild : cs->fChildren) {
+            if (MarkType::kMethod != csChild->fMarkType) {
+                // only check methods for now
                 continue;
             }
-            auto& cs = rootChild;
-            // expect Overview as Topic in every main class or struct
-            auto overview = this->findOverview(cs);
-            if (!overview) {
-                return false;
-            }
-            Definition* memberFunctions = nullptr;
-            for (auto& overChild : overview->fChildren) {
-                if ("Member_Functions" == overChild->fName) {
-                    memberFunctions = overChild;
-                    break;
-                }
+            if (Definition::MethodType::kConstructor == csChild->fMethodType) {
+                continue;
             }
-            if (!memberFunctions) {
-                return overview->reportError<bool>("missing #Subtopic Member_Functions");
+            if (Definition::MethodType::kDestructor == csChild->fMethodType) {
+                continue;
             }
-            if (MarkType::kSubtopic != memberFunctions->fMarkType) {
-                return memberFunctions->reportError<bool>("expected #Subtopic Member_Functions");
+            if (Definition::MethodType::kOperator == csChild->fMethodType) {
+                continue;
             }
-            vector<string> overviewEntries; // build map of overview entries
-            if (!this->collectEntries(memberFunctions, &overviewEntries)) {
+            string name;
+            if (!this->childName(csChild, &name)) {
                 return false;
             }
-            // mark corresponding methods as visited (may be more than one per entry)
-            for (auto& csChild : cs->fChildren) {
-                if (MarkType::kMethod != csChild->fMarkType) {
-                    // only check methods for now
-                    continue;
-                }
-                if (Definition::MethodType::kConstructor == csChild->fMethodType) {
-                    continue;
-                }
-                if (Definition::MethodType::kDestructor == csChild->fMethodType) {
-                    continue;
-                }
-                if (Definition::MethodType::kOperator == csChild->fMethodType) {
-                    continue;
-                }
-                string name;
-                if (!this->childName(csChild, &name)) {
-                    return false;
-                }
-                if (overviewEntries.end() ==
-                        std::find(overviewEntries.begin(), overviewEntries.end(), name)) {
-                    return csChild->reportError<bool>("missing method in Member_Functions");
-                }
+            if (methodEntries.end() ==
+                    std::find(methodEntries.begin(), methodEntries.end(), name)) {
+                return csChild->reportError<bool>("missing method in Member_Functions");
             }
         }
         return true;
@@ -203,17 +184,7 @@ protected:
                 continue;
             }
             auto& cs = rootChild;
-            auto overview = this->findOverview(cs);
-            if (!overview) {
-                return false;
-            }
-            Definition* operators = nullptr;
-            for (auto& overChild : overview->fChildren) {
-                if ("Operators" == overChild->fName) {
-                    operators = overChild;
-                    break;
-                }
-            }
+            const Definition* operators = this->findTopic("Operators", Optional::kYes);
             if (operators && MarkType::kSubtopic != operators->fMarkType) {
                 return operators->reportError<bool>("expected #Subtopic Operators");
             }
@@ -260,22 +231,12 @@ protected:
             if (!overview) {
                 return false;
             }
-            Definition* subtopics = nullptr;
-            Definition* relatedFunctions = nullptr;
-            for (auto& overChild : overview->fChildren) {
-                if ("Subtopics" == overChild->fName) {
-                    subtopics = overChild;
-                } else if ("Related_Functions" == overChild->fName) {
-                    relatedFunctions = overChild;
-                }
-            }
-            if (!subtopics) {
-                return overview->reportError<bool>("missing #Subtopic Subtopics");
-            }
+            const Definition* subtopics = this->findTopic("Subtopics", Optional::kNo);
             if (MarkType::kSubtopic != subtopics->fMarkType) {
                 return subtopics->reportError<bool>("expected #Subtopic Subtopics");
             }
-            if (relatedFunctions && MarkType::kSubtopic != relatedFunctions->fMarkType) {
+			const Definition* relatedFunctions = this->findTopic("Related_Functions", Optional::kYes);
+			if (relatedFunctions && MarkType::kSubtopic != relatedFunctions->fMarkType) {
                 return relatedFunctions->reportError<bool>("expected #Subtopic Related_Functions");
             }
             vector<string> subtopicEntries;
@@ -337,23 +298,57 @@ protected:
         return true;
     }
 
+	static const Definition* overview_def(const Definition* parent) {
+		Definition* overview = nullptr;
+		if (parent) {
+			for (auto& csChild : parent->fChildren) {
+				if ("Overview" == csChild->fName) {
+					if (overview) {
+						return csChild->reportError<const Definition*>("expected only one Overview");
+					}
+					overview = csChild;
+				}
+			}
+		}
+		return overview;
+	}
+
     const Definition* findOverview(const Definition* parent) {
         // expect Overview as Topic in every main class or struct
-        Definition* overview = nullptr;
-        for (auto& csChild : parent->fChildren) {
-            if ("Overview" == csChild->fName) {
-                if (overview) {
-                    return csChild->reportError<const Definition*>("expected only one Overview");
-                }
-                overview = csChild;
-            }
-        }
+        const Definition* overview = overview_def(parent);
+		const Definition* parentOverview = overview_def(parent->fParent);
+		if (overview && parentOverview) {
+			return overview->reportError<const Definition*>("expected only one Overview 2");
+		}
+		overview = overview ? overview : parentOverview;
         if (!overview) {
             return parent->reportError<const Definition*>("missing #Topic Overview");
         }
         return overview;
     }
 
+	enum class Optional {
+		kNo,
+		kYes,
+	};
+
+	const Definition* findTopic(string name, Optional optional) {
+		string topicKey = fRoot->fName + '_' + name;
+		auto topicKeyIter = fBmhParser.fTopicMap.find(topicKey);
+		if (fBmhParser.fTopicMap.end() == topicKeyIter) {
+			// TODO: remove this and require member functions outside of overview
+			topicKey = fRoot->fName + "_Overview_" + name;  // legacy form for now
+			topicKeyIter = fBmhParser.fTopicMap.find(topicKey);
+			if (fBmhParser.fTopicMap.end() == topicKeyIter) {
+				if (Optional::kNo == optional) {
+					return fRoot->reportError<Definition*>("missing subtopic");
+				}
+				return nullptr;
+			}
+		}
+		return topicKeyIter->second;
+	}
+
     bool collectEntries(const Definition* entries, vector<string>* strings) {
         const Definition* table = nullptr;
         for (auto& child : entries->fChildren) {