Add "deprecated:" flag to the spec files.

Also cleanup of the documentation found in the header and html files.

Change-Id: I8a606d1af93b0fd0f912ac23aabdb73aa99233b4

6 files changed, 181 insertions, 141 deletions

diff --git a/api/GenerateHeaderFiles.cpp b/api/GenerateHeaderFiles.cpp
index eb4c9dd8..db94b404 100644
--- a/api/GenerateHeaderFiles.cpp
+++ b/api/GenerateHeaderFiles.cpp
@@ -72,7 +72,8 @@ static void writeVersionGuardEnd(GeneratedFile* file, VersionInfo info) {
 }
 
 static void writeComment(GeneratedFile* file, const string& name, const string& briefComment,
-                         const vector<string>& comment, bool closeBlock) {
+                         const vector<string>& comment, bool addDeprecatedWarning,
+                         bool closeBlock) {
     if (briefComment.empty() && comment.size() == 0) {
         return;
     }
@@ -81,6 +82,10 @@ static void writeComment(GeneratedFile* file, const string& name, const string&
         *file << " * " << name << ": " << briefComment << "\n";
         *file << " *\n";
     }
+    if (addDeprecatedWarning) {
+        *file << " * DEPRECATED.  Do not use.\n";
+        *file << " *\n";
+    }
     for (size_t ct = 0; ct < comment.size(); ct++) {
         string s = stripHtml(comment[ct]);
         s = stringReplace(s, "@", "");
@@ -97,7 +102,8 @@ static void writeComment(GeneratedFile* file, const string& name, const string&
 
 static void writeConstantComment(GeneratedFile* file, const Constant& constant) {
     const string name = constant.getName();
-    writeComment(file, name, constant.getSummary(), constant.getDescription(), true);
+    writeComment(file, name, constant.getSummary(), constant.getDescription(),
+                 constant.deprecated(), true);
 }
 
 static void writeConstantSpecification(GeneratedFile* file, const ConstantSpecification& spec) {
@@ -171,7 +177,7 @@ static void writeTypeSpecification(GeneratedFile* file, const TypeSpecification&
 
 static void writeTypeComment(GeneratedFile* file, const Type& type) {
     const string name = type.getName();
-    writeComment(file, name, type.getSummary(), type.getDescription(), true);
+    writeComment(file, name, type.getSummary(), type.getDescription(), type.deprecated(), true);
 }
 
 static void writeFunctionPermutation(GeneratedFile* file, const FunctionSpecification& spec,
@@ -268,7 +274,8 @@ static void writeFunctionPermutation(GeneratedFile* file, const FunctionSpecific
 
 static void writeFunctionComment(GeneratedFile* file, const Function& function) {
     // Write the generic documentation.
-    writeComment(file, function.getName(), function.getSummary(), function.getDescription(), false);
+    writeComment(file, function.getName(), function.getSummary(), function.getDescription(),
+                 function.deprecated(), false);
 
     // Comment the parameters.
     if (function.someParametersAreDocumented()) {
@@ -276,7 +283,7 @@ static void writeFunctionComment(GeneratedFile* file, const Function& function)
         *file << " * Parameters:\n";
         for (auto p : function.getParameters()) {
             if (!p->documentation.empty()) {
-                *file << " *   " << p->name << " " << p->documentation << "\n";
+                *file << " *   " << p->name << ": " << p->documentation << "\n";
             }
         }
     }
@@ -310,7 +317,8 @@ static bool writeHeaderFile(const string& directory, const SpecFile& specFile) {
     // Write the comments that start the file.
     file.writeNotices();
     writeComment(&file, headerFileName, specFile.getBriefDescription(),
-                 specFile.getFullDescription(), true);
+                 specFile.getFullDescription(), false, true);
+    file << "\n";
 
     // Write the ifndef that prevents the file from being included twice.
     const string guard = makeGuardString(headerFileName);
diff --git a/api/GenerateHtmlDocumentation.cpp b/api/GenerateHtmlDocumentation.cpp
index a9e4d438..1de53289 100644
--- a/api/GenerateHtmlDocumentation.cpp
+++ b/api/GenerateHtmlDocumentation.cpp
@@ -81,8 +81,8 @@ static void writeHtmlHeader(GeneratedFile* file) {
 }
 
 static void writeHtmlFooter(GeneratedFile* file) {
-    *file << "</div> <!-- end body-content -->\n"
-             "</body></html>\n";
+    //*file << "</div>n"
+    *file << "<!-- end body-content -->\n</body></html>\n";
 }
 
 // If prefix starts input, copy it to stream and remove it from input.
@@ -244,14 +244,13 @@ static bool generateHtmlParagraphs(GeneratedFile* file, const vector<string>& de
     return true;
 }
 
-static void writeSummaryTableStart(GeneratedFile* file, const char* label, bool labelIsHeading) {
+static void writeSummaryTableStart(GeneratedFile* file, const string& label, bool labelIsHeading) {
     if (labelIsHeading) {
-        *file << "<h2 style='margin-bottom: 0px;'>" << label << "</h2><hr>\n";
+        *file << "<h2 style='margin-bottom: 0px;'>" << label << "</h2><hr/>\n";
     }
-    //#TODO promethods was the id.  implication?
-    *file << "<table id='id" << label << "' class='jd-sumtable'><tbody>\n";
+    *file << "<table class='jd-sumtable'><tbody>\n";
     if (!labelIsHeading) {
-        *file << "  <tr><th colspan='12'>" << label << "</th></tr>\n";
+        *file << "  <tr><th colspan='2'>" << label << "</th></tr>\n";
     }
 }
 
@@ -259,86 +258,83 @@ static void writeSummaryTableEnd(GeneratedFile* file) {
     *file << "</tbody></table>\n";
 }
 
-static void writeSummaryTableEntry(GeneratedFile* file, Constant* constant) {
-    if (constant->hidden()) {
+enum DeprecatedSelector {
+    DEPRECATED_ONLY,
+    NON_DEPRECATED_ONLY,
+    ALL,
+};
+
+static void writeSummaryTableEntry(ostream* stream, Definition* definition,
+                                   DeprecatedSelector deprecatedSelector) {
+    if (definition->hidden()) {
         return;
     }
-    *file << "  <tr class='alt-color api apilevel-1'>\n";
-    *file << "    <td class='jd-linkcol'><nobr>\n";
-    *file << "      <a href='" << constant->getUrl() << "'>" << constant->getName()
-          << "</a></nobr>\n";
-    *file << "    </td>\n";
-    *file << "    <td class='jd-descrcol' width='100%'><nobr>\n";
-    *file << "        " << constant->getSummary() << "\n";
-    *file << "    </td>\n";
-    *file << "  </tr>\n";
-}
-
-static void writeSummaryTableEntry(GeneratedFile* file, Type* type) {
-    if (type->hidden()) {
+    const bool deprecated = definition->deprecated();
+    if ((deprecatedSelector == DEPRECATED_ONLY && !deprecated) ||
+        (deprecatedSelector == NON_DEPRECATED_ONLY && deprecated)) {
         return;
     }
-    *file << "  <tr class='alt-color api apilevel-1'>\n";
-    *file << "    <td class='jd-linkcol'><nobr>\n";
-    *file << "      <a href='" << type->getUrl() << "'>" << type->getName() << "</a></nobr>\n";
-    *file << "    </td>\n";
-    *file << "    <td class='jd-descrcol' width='100%'><nobr>\n";
-    *file << "        " << type->getSummary() << "\n";
-    *file << "    </td>\n";
-    *file << "  </tr>\n";
+
+    *stream << "  <tr class='alt-color api apilevel-1'>\n";
+    *stream << "    <td class='jd-linkcol'>\n";
+    *stream << "      <a href='" << definition->getUrl() << "'>" << definition->getName() << "</a>\n";
+    *stream << "    </td>\n";
+    *stream << "    <td class='jd-descrcol' width='100%'>\n";
+    *stream << "      ";
+    if (deprecated) {
+        *stream << "<b>Deprecated</b>.  ";
+    }
+    *stream << definition->getSummary() << "\n";
+    *stream << "    </td>\n";
+    *stream << "  </tr>\n";
 }
 
-static void writeSummaryTableEntry(GeneratedFile* file, Function* function) {
-    *file << "  <tr class='alt-color api apilevel-1'>\n";
-    *file << "    <td class='jd-linkcol'>\n";
-    *file << "      <a href='" << function->getUrl() << "'>" << function->getName() << "</a>\n";
-    *file << "    </td>\n";
-    *file << "    <td class='jd-linkcol' width='100%'>\n";  // TODO jd-typecol
-    //    *file << "      <nobr><span class='sympad'></span></nobr>\n";
-    *file << "      <div class='jd-descrdiv'>\n";
-    *file << "        " << function->getSummary() << "\n";
-    *file << "      </div>\n";
-    *file << "    </td>\n";
-    *file << "  </tr>\n";
+static void writeSummaryTable(GeneratedFile* file, const ostringstream* entries, const char* name,
+                              DeprecatedSelector deprecatedSelector, bool labelAsHeader) {
+    string s = entries->str();
+    if (!s.empty()) {
+        string prefix;
+        if (deprecatedSelector == DEPRECATED_ONLY) {
+            prefix = "Deprecated ";
+        }
+        writeSummaryTableStart(file, prefix + name, labelAsHeader);
+        *file << s;
+        writeSummaryTableEnd(file);
+    }
 }
 
 static void writeSummaryTables(GeneratedFile* file, const map<string, Constant*>& constants,
                                const map<string, Type*>& types,
-                               const map<string, Function*>& functions, bool labelAsHeader) {
-    if (constants.size() > 0) {
-        writeSummaryTableStart(file, "Constants", labelAsHeader);
-        for (auto e : constants) {
-            writeSummaryTableEntry(file, e.second);
-        }
-        writeSummaryTableEnd(file);
+                               const map<string, Function*>& functions,
+                               DeprecatedSelector deprecatedSelector, bool labelAsHeader) {
+    ostringstream constantStream;
+    for (auto e : constants) {
+        writeSummaryTableEntry(&constantStream, e.second, deprecatedSelector);
     }
+    writeSummaryTable(file, &constantStream, "Constants", deprecatedSelector, labelAsHeader);
 
-    if (types.size() > 0) {
-        writeSummaryTableStart(file, "Types", labelAsHeader);
-        for (auto e : types) {
-            writeSummaryTableEntry(file, e.second);
-        }
-        writeSummaryTableEnd(file);
+    ostringstream typeStream;
+    for (auto e : types) {
+        writeSummaryTableEntry(&typeStream, e.second, deprecatedSelector);
     }
+    writeSummaryTable(file, &typeStream, "Types", deprecatedSelector, labelAsHeader);
 
-    if (functions.size() > 0) {
-        writeSummaryTableStart(file, "Functions", labelAsHeader);
-        for (auto e : functions) {
-            writeSummaryTableEntry(file, e.second);
-        }
-        writeSummaryTableEnd(file);
+    ostringstream functionStream;
+    for (auto e : functions) {
+        writeSummaryTableEntry(&functionStream, e.second, deprecatedSelector);
     }
+    writeSummaryTable(file, &functionStream, "Functions", deprecatedSelector, labelAsHeader);
 }
 
 static void writeHtmlVersionTag(GeneratedFile* file, VersionInfo info) {
+    ostringstream stream;
     if (info.intSize == 32) {
-        *file << "For 32 bits: ";
+        stream << "When compiling for 32 bits. ";
     } else if (info.intSize == 64) {
-        *file << "For 64 bits: ";
+        stream << "When compiling for 64 bits. ";
     }
 
     if (info.minVersion > 1 || info.maxVersion) {
-        *file << "<div>";
         const char* mid =
                     "<a "
                     "href='http://developer.android.com/guide/topics/manifest/"
@@ -346,64 +342,81 @@ static void writeHtmlVersionTag(GeneratedFile* file, VersionInfo info) {
         if (info.minVersion <= 1) {
             // No minimum
             if (info.maxVersion > 0) {
-                *file << "Removed from " << mid << info.maxVersion + 1;
+                stream << "Removed from " << mid << info.maxVersion + 1;
             }
         } else {
             if (info.maxVersion == 0) {
                 // No maximum
-                *file << "Added in " << mid << info.minVersion;
+                stream << "Added in " << mid << info.minVersion;
             } else {
-                *file << mid << info.minVersion << " - " << info.maxVersion;
+                stream << mid << info.minVersion << " - " << info.maxVersion;
             }
         }
-        *file << "</a></div>\n";
+        stream << "</a>";
+    }
+    const string s = stream.str();
+    if (!s.empty()) {
+        // TODO simplify
+        //*file << "    <p>" << s << "</p>\n";
+        *file << "    " << s << "\n";
     }
 }
 
-static void writeDetailedType(GeneratedFile* file, const TypeSpecification* type) {
+
+static void writeDetailedTypeSpecification(GeneratedFile* file, const TypeSpecification* type) {
     switch (type->getKind()) {
         case SIMPLE:
-            *file << "Base type: " << type->getSimpleType() << "\n";
+            *file << "<p>A typedef of: " << type->getSimpleType()
+                  << "&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;";
+            writeHtmlVersionTag(file, type->getVersionInfo());
+            *file << "</p>\n";
             break;
         case ENUM: {
-            *file << "An enum<br>\n";
-            *file << "    <table class='jd-tagtable'><tbody>\n";
+            *file << "<p>An enum with the following values:&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\n";
+            writeHtmlVersionTag(file, type->getVersionInfo());
+            *file << "</p>\n";
 
+            *file << "  <table class='jd-tagtable'><tbody>\n";
             const vector<string>& values = type->getValues();
             const vector<string>& valueComments = type->getValueComments();
             for (size_t i = 0; i < values.size(); i++) {
-                *file << "    <tr><th>" << values[i] << "</th>";
-                if (valueComments.size() > i && !valueComments[i].empty()) {
-                    *file << "<td>" << valueComments[i] << "</td>";
+                *file << "    <tr><th>" << values[i] << "</th><td>";
+                if (valueComments.size() > i) {
+                    *file << valueComments[i];
                 }
-                *file << "</tr>\n";
+                *file << "</td></tr>\n";
             }
-            *file << "    </tbody></table>\n";
+            *file << "  </tbody></table><br/>\n";
             break;
         }
         case STRUCT: {
             // TODO string mStructName;             // The name found after the struct keyword
-            *file << "A structure<br>\n";
-            *file << "    <table class='jd-tagtable'><tbody>\n";
+            *file << "<p>A structure with the following fields:&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;";
+            writeHtmlVersionTag(file, type->getVersionInfo());
+            *file << "</p>\n";
+
+            *file << "  <table class='jd-tagtable'><tbody>\n";
             const vector<string>& fields = type->getFields();
             const vector<string>& fieldComments = type->getFieldComments();
             for (size_t i = 0; i < fields.size(); i++) {
-                *file << "    <tr><th>" << fields[i] << "</th>";
+                *file << "    <tr><th>" << fields[i] << "</th><td>";
                 if (fieldComments.size() > i && !fieldComments[i].empty()) {
-                    *file << "<td>" << fieldComments[i] << "</td>";
+                    *file << fieldComments[i];
                 }
-                *file << "</tr>\n";
+                *file << "</td></tr>\n";
             }
-            *file << "    </tbody></table>\n";
+            *file << "  </tbody></table><br/>\n";
             break;
         }
     }
-    writeHtmlVersionTag(file, type->getVersionInfo());
 }
 
-static void writeDetailedConstant(GeneratedFile* file, ConstantSpecification* c) {
+static void writeDetailedConstantSpecification(GeneratedFile* file, ConstantSpecification* c) {
+    *file << "      <tr><td>";
     *file << "Value: " << c->getValue() << "\n";
     writeHtmlVersionTag(file, c->getVersionInfo());
+    *file << "      </td></tr>\n";
+    *file << "<br/>\n";
 }
 
 static bool writeOverviewForFile(GeneratedFile* file, const SpecFile& specFile) {
@@ -416,7 +429,8 @@ static bool writeOverviewForFile(GeneratedFile* file, const SpecFile& specFile)
     // Write the summary tables.
     // file << "<h2>Summary</h2>\n";
     writeSummaryTables(file, specFile.getDocumentedConstants(), specFile.getDocumentedTypes(),
-                       specFile.getDocumentedFunctions(), false);
+                       specFile.getDocumentedFunctions(), NON_DEPRECATED_ONLY, false);
+
     return success;
 }
 
@@ -428,8 +442,7 @@ static bool generateOverview(const string& directory) {
     bool success = true;
     writeHtmlHeader(&file);
 
-    file << "<h1 itemprop='name'>Overview</h1>\n";
-    // TODO Have the overview text here!
+    file << "<h1>Overview</h1>\n";
 
     for (auto specFile : systemSpecification.getSpecFiles()) {
         if (!writeOverviewForFile(&file, *specFile)) {
@@ -450,13 +463,30 @@ static bool generateAlphabeticalIndex(const string& directory) {
     writeHtmlHeader(&file);
 
     writeSummaryTables(&file, systemSpecification.getConstants(), systemSpecification.getTypes(),
-                       systemSpecification.getFunctions(), true);
+                       systemSpecification.getFunctions(), NON_DEPRECATED_ONLY, true);
+
+    writeSummaryTables(&file, systemSpecification.getConstants(), systemSpecification.getTypes(),
+                       systemSpecification.getFunctions(), DEPRECATED_ONLY, true);
 
     writeHtmlFooter(&file);
     file.close();
     return true;
 }
 
+static void writeDeprecatedWarning(GeneratedFile* file, Definition* definition) {
+    if (definition->deprecated()) {
+        *file << "    <p><b>Deprecated.</b>  ";
+        string s = definition->getDeprecatedMessage();
+        convertDocumentationRefences(&s);
+        if (!s.empty()) {
+            *file << s;
+        } else {
+            *file << "Do not use.";
+        }
+        *file << "</p>\n";
+    }
+}
+
 static bool writeDetailedConstant(GeneratedFile* file, Constant* constant) {
     if (constant->hidden()) {
         return true;
@@ -465,7 +495,7 @@ static bool writeDetailedConstant(GeneratedFile* file, Constant* constant) {
 
     // TODO need names that distinguish fn.const. type
     // TODO had attr_android:...
-    *file << "<a name='android_rs:" << name << "'></a>\n";
+    *file << "<a id='android_rs:" << name << "'></a>\n";
     *file << "<div class='jd-details'>\n";
     *file << "  <h4 class='jd-details-title'>\n";
     *file << "    <span class='sympad'>" << name << "</span>\n";
@@ -474,17 +504,20 @@ static bool writeDetailedConstant(GeneratedFile* file, Constant* constant) {
 
     *file << "  <div class='jd-details-descr'>\n";
     *file << "    <table class='jd-tagtable'><tbody>\n";
-    for (auto f : constant->getSpecifications()) {
-        *file << "      <tr><td>";
-        writeDetailedConstant(file, f);
-        *file << "      </td></tr>\n";
-        *file << "<br/>\n";
+    auto specifications = constant->getSpecifications();
+    bool addSeparator = specifications.size() > 1;
+    for (auto spec : specifications) {
+        if (addSeparator) {
+            *file << "    <h5 class='jd-tagtitle'>Variant:</h5>\n";
+        }
+        writeDetailedConstantSpecification(file, spec);
     }
     *file << "    </tbody></table>\n";
     *file << "  </div>\n";
 
     *file << "    <div class='jd-tagdata jd-tagdescr'>\n";
 
+    writeDeprecatedWarning(file, constant);
     if (!generateHtmlParagraphs(file, constant->getDescription())) {
         return false;
     }
@@ -503,7 +536,7 @@ static bool writeDetailedType(GeneratedFile* file, Type* type) {
 
     // TODO need names that distinguish fn.const. type
     // TODO had attr_android:...
-    *file << "<a name='android_rs:" << name << "'></a>\n";
+    *file << "<a id='android_rs:" << name << "'></a>\n";
     *file << "<div class='jd-details'>\n";
     *file << "  <h4 class='jd-details-title'>\n";
     *file << "    <span class='sympad'>" << name << "</span>\n";
@@ -511,25 +544,16 @@ static bool writeDetailedType(GeneratedFile* file, Type* type) {
     *file << "  </h4>\n";
 
     *file << "  <div class='jd-details-descr'>\n";
-    *file << "    <h5 class='jd-tagtitle'>Variants</h5>\n";
-    *file << "    <table class='jd-tagtable'><tbody>\n";
-    for (auto f : type->getSpecifications()) {
-        *file << "      <tr><td>";
-        writeDetailedType(file, f);
-        *file << "      </td></tr>\n";
-        *file << "<br/>\n";
+    for (auto spec : type->getSpecifications()) {
+        writeDetailedTypeSpecification(file, spec);
     }
-    *file << "    </tbody></table>\n";
-    *file << "  </div>\n";
-
-    *file << "    <div class='jd-tagdata jd-tagdescr'>\n";
 
+    writeDeprecatedWarning(file, type);
     if (!generateHtmlParagraphs(file, type->getDescription())) {
         return false;
     }
 
-    *file << "    </div>\n";
-
+    *file << "  </div>\n";
     *file << "</div>\n";
     *file << "\n";
     return true;
@@ -540,7 +564,7 @@ static bool writeDetailedFunction(GeneratedFile* file, Function* function) {
 
     // TODO need names that distinguish fn.const. type
     // TODO had attr_android:...
-    *file << "<a name='android_rs:" << name << "'></a>\n";
+    *file << "<a id='android_rs:" << name << "'></a>\n";
     *file << "<div class='jd-details'>\n";
     *file << "  <h4 class='jd-details-title'>\n";
     *file << "    <span class='sympad'>" << name << "</span>\n";
@@ -548,17 +572,17 @@ static bool writeDetailedFunction(GeneratedFile* file, Function* function) {
     *file << "  </h4>\n";
 
     *file << "  <div class='jd-details-descr'>\n";
-    *file << "    <table class='jd-tagtable'><tbody>\n";
     map<string, DetailedFunctionEntry> entries;
     if (!getUnifiedFunctionPrototypes(function, &entries)) {
         return false;
     }
+    *file << "    <table class='jd-tagtable'><tbody>\n";
     for (auto i : entries) {
         *file << "      <tr>\n";
-        *file << "        <td>" << i.second.htmlDeclaration << "<td/>\n";
+        *file << "        <td>" << i.second.htmlDeclaration << "</td>\n";
         *file << "        <td>";
         writeHtmlVersionTag(file, i.second.info);
-        *file << "</td>\n";
+        *file << "        </td>\n";
         *file << "      </tr>\n";
     }
     *file << "    </tbody></table>\n";
@@ -586,6 +610,7 @@ static bool writeDetailedFunction(GeneratedFile* file, Function* function) {
     }
 
     *file << "  <div class='jd-tagdata jd-tagdescr'>\n";
+    writeDeprecatedWarning(file, function);
     if (!generateHtmlParagraphs(file, function->getDescription())) {
         return false;
     }
@@ -608,8 +633,7 @@ static bool writeDetailedDocumentationFile(const string& directory, const SpecFi
     file << "<br/>";
 
     // Write the file documentation.
-    file << "<h1 itemprop='name'>" << specFile.getBriefDescription()
-         << "</h1>\n";  // TODO not sure about itemprop
+    file << "<h1>" << specFile.getBriefDescription() << "</h1>\n";
 
     file << "<h2>Overview</h2>\n";
     if (!generateHtmlParagraphs(&file, specFile.getFullDescription())) {
@@ -621,7 +645,9 @@ static bool writeDetailedDocumentationFile(const string& directory, const SpecFi
     const auto& constants = specFile.getDocumentedConstants();
     const auto& types = specFile.getDocumentedTypes();
     const auto& functions = specFile.getDocumentedFunctions();
-    writeSummaryTables(&file, constants, types, functions, false);
+
+    writeSummaryTables(&file, constants, types, functions, NON_DEPRECATED_ONLY, false);
+    writeSummaryTables(&file, constants, types, functions, DEPRECATED_ONLY, false);
 
     // Write the full details of each constant, type, and function.
     if (!constants.empty()) {
diff --git a/api/Scanner.h b/api/Scanner.h
index 593ff493..c3d6f337 100644
--- a/api/Scanner.h
+++ b/api/Scanner.h
@@ -20,7 +20,7 @@
 #include <fstream>
 #include <string>
 
-class ParameterEntry;
+struct ParameterEntry;
 
 class Scanner {
 private:
diff --git a/api/Specification.cpp b/api/Specification.cpp
index 92d14d61..fbbbc21f 100644
--- a/api/Specification.cpp
+++ b/api/Specification.cpp
@@ -214,7 +214,7 @@ void VersionInfo::scan(Scanner* scanner) {
     }
 }
 
-Definition::Definition(const std::string& name) : mName(name), mHidden(false) {
+Definition::Definition(const std::string& name) : mName(name), mDeprecated(false), mHidden(false) {
 }
 
 void Definition::scanDocumentationTags(Scanner* scanner, bool firstOccurence,
@@ -223,6 +223,10 @@ void Definition::scanDocumentationTags(Scanner* scanner, bool firstOccurence,
         scanner->checkNoValue();
         mHidden = true;
     }
+    if (scanner->findOptionalTag("deprecated:")) {
+        mDeprecated = true;
+        mDeprecatedMessage = scanner->getValue();
+    }
     if (firstOccurence) {
         if (scanner->findTag("summary:")) {
             mSummary = scanner->getValue();
@@ -561,7 +565,7 @@ void FunctionSpecification::scanFunctionSpecification(Scanner* scanner, SpecFile
 
 FunctionPermutation::FunctionPermutation(Function* func, FunctionSpecification* spec,
                                          int replacementIndexes[MAX_REPLACEABLES], Scanner* scanner)
-    : mFunction(func), mReturn(nullptr), mInputCount(0), mOutputCount(0) {
+    : mReturn(nullptr), mInputCount(0), mOutputCount(0) {
     // We expand the strings now to make capitalization easier.  The previous code preserved
     // the #n
     // markers just before emitting, which made capitalization difficult.
diff --git a/api/Specification.h b/api/Specification.h
index f5211f03..3fa1aa37 100644
--- a/api/Specification.h
+++ b/api/Specification.h
@@ -137,6 +137,8 @@ struct VersionInfo {
 class Definition {
 protected:
     std::string mName;
+    bool mDeprecated;                       // True if this API should not be used
+    std::string mDeprecatedMessage;         // Optional specific warning if the API is deprecated
     bool mHidden;                           // True if it should not be documented
     std::string mSummary;                   // A one-line description
     std::vector<std::string> mDescription;  // The comments to be included in the header
@@ -146,6 +148,8 @@ public:
     Definition(const std::string& name);
 
     std::string getName() const { return mName; }
+    bool deprecated() const { return mDeprecated; }
+    std::string getDeprecatedMessage() const { return mDeprecatedMessage; }
     bool hidden() const { return mHidden; }
     std::string getSummary() const { return mSummary; }
     const std::vector<std::string>& getDescription() const { return mDescription; }
@@ -340,7 +344,6 @@ private:
      */
     std::string mUnexpandedName;
     ParameterEntry* mReturn;  // The return type. The name should be empty.  Owned.
-    int mReturnLineNumber;
     std::vector<ParameterEntry*> mParameters;  // The parameters.  Owned.
     std::vector<std::string> mInline;          // The inline code to be included in the header
 
@@ -391,8 +394,6 @@ public:
  */
 class FunctionPermutation {
 private:
-    Function* mFunction;  // NOT OWNED.
-
     // These are the expanded version of those found on FunctionSpecification
     std::string mName;
     std::string mNameTrunk;  // The name without any expansion, e.g. convert
diff --git a/api/Utilities.cpp b/api/Utilities.cpp
index b372b13a..6464ae17 100644
--- a/api/Utilities.cpp
+++ b/api/Utilities.cpp
@@ -39,7 +39,7 @@ const char LEGAL_NOTICE[] =
             " */\n\n";
 
 const char AUTO_GENERATED_WARNING[] =
-            "Don't edit this file!  It is auto-generated by frameworks/rs/api/gen_runtime.";
+            "Don't edit this file!  It is auto-generated by frameworks/rs/api/generate.sh.";
 
 string capitalize(const string& source) {
     int length = source.length();
@@ -95,28 +95,29 @@ bool charRemoved(char c, string* s) {
 }
 
 string stripHtml(const string& html) {
-    string s;
-    for (size_t start = 0; start < html.size(); start++) {
-        size_t lt = html.find('<', start);
+    string in = stringReplace(html, "<li>", "- ");
+    string out;
+    for (size_t start = 0; start < in.size(); start++) {
+        size_t lt = in.find('<', start);
         if (lt == string::npos) {
-            s += html.substr(start);
+            out += in.substr(start);
             break;
         }
-        s += html.substr(start, lt - start);
-        if (isalpha(html[lt + 1]) || html[lt + 1] == '/') {
+        out += in.substr(start, lt - start);
+        if (isalpha(in[lt + 1]) || in[lt + 1] == '/') {
             // It's an HTML tag.  Search for the end.
-            start = html.find('>', lt + 1);
+            start = in.find('>', lt + 1);
             if (start == string::npos) {
                 break;
             }
         } else {
-            s += '<';
+            out += '<';
         }
     }
-    s = stringReplace(s, "&gt;", ">");
-    s = stringReplace(s, "&lt;", "<");
-    s = stringReplace(s, "&nbsp;", " ");
-    return s;
+    out = stringReplace(out, "&gt;", ">");
+    out = stringReplace(out, "&lt;", "<");
+    out = stringReplace(out, "&nbsp;", " ");
+    return out;
 }
 
 string hashString(const string& s) {