fix param return descriptions

enforce that param and return
descriptions are phrases (begin
with lower case, no trailing
period).

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

3 files changed, 47 insertions, 11 deletions

diff --git a/tools/bookmaker/bookmaker.cpp b/tools/bookmaker/bookmaker.cpp
index 0c23c7720a..b3d3190b78 100644
--- a/tools/bookmaker/bookmaker.cpp
+++ b/tools/bookmaker/bookmaker.cpp
@@ -28,6 +28,7 @@ enum comments should be disallowed unless after #Enum and before first #Const
 trouble with aliases, plurals
     need to keep first letter of includeWriter @param / @return lowercase
     Quad -> quad, Quads -> quads
+check for summary containing all methods
  */
 
 static string normalized_name(string name) {
@@ -1028,16 +1029,8 @@ bool BmhParser::addDefinition(const char* defStart, bool hasEnd, MarkType markTy
                         return false;
                     }
                     if (MarkType::kParam == markType || MarkType::kReturn == markType) {
-                        const char* parmEndCheck = definition->fContentEnd;
-                        while (parmEndCheck < definition->fTerminator) {
-                            if (fMC == parmEndCheck[0]) {
-                                break;
-                            }
-                            if (' ' < parmEndCheck[0]) {
-                                this->reportError<bool>(
-                                        "use full end marker on multiline #Param and #Return");
-                            }
-                            ++parmEndCheck;
+                        if (!this->checkParamReturn(definition)) {
+                            return false;
                         }
                     }
                 } else {
@@ -1225,6 +1218,21 @@ bool BmhParser::checkExamples() const {
     return checkOK;
 }
 
+bool BmhParser::checkParamReturn(const Definition* definition) const {
+    const char* parmEndCheck = definition->fContentEnd;
+    while (parmEndCheck < definition->fTerminator) {
+        if (fMC == parmEndCheck[0]) {
+            break;
+        }
+        if (' ' < parmEndCheck[0]) {
+            this->reportError<bool>(
+                    "use full end marker on multiline #Param and #Return");
+        }
+        ++parmEndCheck;
+    }
+    return true;
+}
+
 bool BmhParser::childOf(MarkType markType) const {
     auto childError = [this](MarkType markType) -> bool {
         string errStr = "expected ";
@@ -2181,7 +2189,7 @@ int main(int argc, char** const argv) {
         return 0;
     }
     if ((FLAGS_include.isEmpty() || FLAGS_bmh.isEmpty()) && FLAGS_populate) {
-        SkDebugf("-r requires -b -i\n");
+        SkDebugf("-p requires -b -i\n");
         SkCommandLineFlags::PrintUsage();
         return 1;
     }
diff --git a/tools/bookmaker/bookmaker.h b/tools/bookmaker/bookmaker.h
index 0f0693fd77..71ff0d5dd6 100644
--- a/tools/bookmaker/bookmaker.h
+++ b/tools/bookmaker/bookmaker.h
@@ -1290,6 +1290,7 @@ public:
     bool addDefinition(const char* defStart, bool hasEnd, MarkType markType,
             const vector<string>& typeNameBuilder);
     bool checkExamples() const;
+    bool checkParamReturn(const Definition* definition) const;
     bool dumpExamples(const char* fiddleJsonFileName) const;
     bool childOf(MarkType markType) const;
     string className(MarkType markType);
@@ -1794,6 +1795,7 @@ private:
 
     string addReferences(const char* start, const char* end, BmhParser::Resolvable );
     bool buildRefFromFile(const char* fileName, const char* outDir);
+    bool checkParamReturnBody(const Definition* def) const;
     void childrenOut(const Definition* def, const char* contentStart);
     const Definition* isDefined(const TextParser& parser, const string& ref, bool report) const;
     string linkName(const Definition* ) const;
diff --git a/tools/bookmaker/mdOut.cpp b/tools/bookmaker/mdOut.cpp
index 744122a0a4..3718151e76 100644
--- a/tools/bookmaker/mdOut.cpp
+++ b/tools/bookmaker/mdOut.cpp
@@ -283,6 +283,26 @@ bool MdOut::buildRefFromFile(const char* name, const char* outDir) {
     return true;
 }
 
+bool MdOut::checkParamReturnBody(const Definition* def) const {
+    TextParser paramBody(def);
+    const char* descriptionStart = paramBody.fChar;
+    if (!islower(descriptionStart[0])) {
+        paramBody.skipToNonAlphaNum();
+        string ref = string(descriptionStart, paramBody.fChar - descriptionStart);
+        if (!this->isDefined(paramBody, ref, true)) {
+            string errorStr = MarkType::kReturn == def->fMarkType ? "return" : "param";
+            errorStr += " description must start with lower case";
+            paramBody.reportError(errorStr.c_str());
+            return false;
+        }
+    }
+    if ('.' == paramBody.fEnd[-1]) {
+        paramBody.reportError("make param description a phrase; should not end with period");
+        return false;
+    }
+    return true;
+}
+
 void MdOut::childrenOut(const Definition* def, const char* start) {
     const char* end;
     fLineCount = def->fLineCount;
@@ -719,6 +739,9 @@ void MdOut::markTypeOut(Definition* def) {
             const char* paramName = paramParser.fChar;
             paramParser.skipToSpace();
             string paramNameStr(paramName, (int) (paramParser.fChar - paramName));
+            if (!this->checkParamReturnBody(def)) {
+                return;
+            }
             string refNameStr = def->fParent->fFiddle + "_" + paramNameStr;
             fprintf(fOut, 
                     "    <td><a name=\"%s\"> <code><strong>%s </strong></code> </a></td> <td>",
@@ -731,6 +754,9 @@ void MdOut::markTypeOut(Definition* def) {
         case MarkType::kReturn:
             this->mdHeaderOut(3);
             fprintf(fOut, "Return Value");
+            if (!this->checkParamReturnBody(def)) {
+                return;
+            }
             this->lf(2);
             break;
         case MarkType::kRow: