| /* | |
| * Copyright (C) 2015 The Android Open Source Project | |
| * | |
| * Licensed under the Apache License, Version 2.0 (the "License"); | |
| * you may not use this file except in compliance with the License. | |
| * You may obtain a copy of the License at | |
| * | |
| * http://www.apache.org/licenses/LICENSE-2.0 | |
| * | |
| * Unless required by applicable law or agreed to in writing, software | |
| * distributed under the License is distributed on an "AS IS" BASIS, | |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | |
| * See the License for the specific language governing permissions and | |
| * limitations under the License. | |
| */ | |
| #include <iostream> | |
| #include <sstream> | |
| #include "Generator.h" | |
| #include "Specification.h" | |
| #include "Utilities.h" | |
| using namespace std; | |
| struct DetailedFunctionEntry { | |
| VersionInfo info; | |
| string htmlDeclaration; | |
| }; | |
| static const char OVERVIEW_HTML_FILE_NAME[] = "overview.html"; | |
| static const char OVERVIEW_JD_FILE_NAME[] = "overview.jd"; | |
| static const char INDEX_HTML_FILE_NAME[] = "index.html"; | |
| static const char INDEX_JD_FILE_NAME[] = "index.jd"; | |
| static void writeHeader(GeneratedFile* file, bool forVerification, const string& title) { | |
| if (forVerification) { | |
| *file << "<!DOCTYPE html>\n"; | |
| *file << "<!-- " << AUTO_GENERATED_WARNING << "-->\n"; | |
| *file << "<html><head>\n" | |
| "<title>RenderScript Reference</title>\n" | |
| "<meta http-equiv='Content-Type' content='text/html; charset=UTF-8'>\n" | |
| "<link rel='stylesheet' " | |
| "href='http://fonts.googleapis.com/css?family=Roboto+Condensed'>\n" | |
| "<link rel='stylesheet' href='http://fonts.googleapis.com/" | |
| "css?family=Roboto:light,regular,medium,thin,italic,mediumitalic,bold' " | |
| "title='roboto'>\n" | |
| "<link href='default.css' rel='stylesheet' type='text/css'>\n" | |
| "<link href='fullscreen.css' rel='stylesheet' class='fullscreen' " | |
| "type='text/css'>\n" | |
| "<body class='gc-documentation develop reference'>\n\n"; | |
| *file << "<h1>" << title << "</h1>\n"; | |
| } else { | |
| *file << "page.title=RenderScript " << title << "\n\n"; | |
| *file << "@jd:body\n\n"; | |
| } | |
| *file << "<div class='renderscript'>\n"; | |
| } | |
| static void writeFooter(GeneratedFile* file, bool forVerification) { | |
| *file << "</div>\n"; | |
| if (forVerification) { | |
| *file << "</body></html>\n"; | |
| } | |
| } | |
| // If prefix starts input, copy it to stream and remove it from input. | |
| static void skipPrefix(ostringstream* stream, string* input, const string& prefix) { | |
| size_t size = prefix.size(); | |
| if (input->compare(0, size, prefix) != 0) { | |
| return; | |
| } | |
| input->erase(0, size); | |
| *stream << prefix; | |
| } | |
| // Merge b into a. Returns true if successful | |
| static bool mergeVersionInfo(VersionInfo* a, const VersionInfo& b) { | |
| if (a->intSize != b.intSize) { | |
| cerr << "Error. We don't currently support versions that differ based on int size\n"; | |
| return false; | |
| } | |
| if (b.minVersion != 0 && a->maxVersion == b.minVersion - 1) { | |
| a->maxVersion = b.maxVersion; | |
| } else if (b.maxVersion != 0 && a->minVersion == b.maxVersion + 1) { | |
| a->minVersion = b.minVersion; | |
| } else { | |
| cerr << "Error. This code currently assume that all versions are contiguous. Don't know " | |
| "how to merge versions (" << a->minVersion << " - " << a->maxVersion << ") and (" | |
| << b.minVersion << " - " << b.maxVersion << ")\n"; | |
| return false; | |
| } | |
| return true; | |
| } | |
| static string getHtmlStringForType(const ParameterDefinition& parameter) { | |
| string s = parameter.rsType; | |
| ostringstream stream; | |
| skipPrefix(&stream, &s, "const "); | |
| skipPrefix(&stream, &s, "volatile "); | |
| bool endsWithAsterisk = s.size() > 0 && s[s.size() - 1] == '*'; | |
| if (endsWithAsterisk) { | |
| s.erase(s.size() - 1, 1); | |
| } | |
| string anchor = systemSpecification.getHtmlAnchor(s); | |
| if (anchor.empty()) { | |
| // Not a RenderScript specific type. | |
| return parameter.rsType; | |
| } else { | |
| stream << anchor; | |
| } | |
| if (endsWithAsterisk) { | |
| stream << "*"; | |
| } | |
| return stream.str(); | |
| } | |
| static string getDetailedHtmlDeclaration(const FunctionPermutation& permutation) { | |
| ostringstream stream; | |
| auto ret = permutation.getReturn(); | |
| if (ret) { | |
| stream << getHtmlStringForType(*ret); | |
| } else { | |
| stream << "void"; | |
| } | |
| stream << " " << permutation.getName() << "("; | |
| bool needComma = false; | |
| for (auto p : permutation.getParams()) { | |
| if (needComma) { | |
| stream << ", "; | |
| } | |
| stream << getHtmlStringForType(*p); | |
| if (p->isOutParameter) { | |
| stream << "*"; | |
| } | |
| if (!p->specName.empty()) { | |
| stream << " " << p->specName; | |
| } | |
| needComma = true; | |
| } | |
| stream << ");\n"; | |
| return stream.str(); | |
| } | |
| /* Some functions (like max) have changed implementations but not their | |
| * declaration. We need to unify these so that we don't end up with entries | |
| * like: | |
| * char max(char a, char b); Removed from API level 20 | |
| * char max(char a, char b); Added to API level 20 | |
| */ | |
| static bool getUnifiedFunctionPrototypes(Function* function, | |
| map<string, DetailedFunctionEntry>* entries) { | |
| for (auto f : function->getSpecifications()) { | |
| DetailedFunctionEntry entry; | |
| entry.info = f->getVersionInfo(); | |
| for (auto p : f->getPermutations()) { | |
| entry.htmlDeclaration = getDetailedHtmlDeclaration(*p); | |
| const string s = stripHtml(entry.htmlDeclaration); | |
| auto i = entries->find(s); | |
| if (i == entries->end()) { | |
| entries->insert(pair<string, DetailedFunctionEntry>(s, entry)); | |
| } else { | |
| if (!mergeVersionInfo(&i->second.info, entry.info)) { | |
| return false; | |
| } | |
| } | |
| } | |
| } | |
| return true; | |
| } | |
| // Convert words starting with @ into HTML references. Returns false if error. | |
| static bool convertDocumentationRefences(string* s) { | |
| bool success = true; | |
| size_t end = 0; | |
| for (;;) { | |
| size_t start = s->find('@', end); | |
| if (start == string::npos) { | |
| break; | |
| } | |
| // Find the end of the identifier | |
| end = start; | |
| char c; | |
| do { | |
| c = (*s)[++end]; | |
| } while (isalnum(c) || c == '_'); | |
| const string id = s->substr(start + 1, end - start - 1); | |
| string anchor = systemSpecification.getHtmlAnchor(id); | |
| if (anchor.empty()) { | |
| cerr << "Error: Can't convert the documentation reference @" << id << "\n"; | |
| success = false; | |
| } | |
| s->replace(start, end - start, anchor); | |
| } | |
| return success; | |
| } | |
| static bool generateHtmlParagraphs(GeneratedFile* file, const vector<string>& description) { | |
| bool inParagraph = false; | |
| for (auto s : description) { | |
| // Empty lines in the .spec marks paragraphs. | |
| if (s.empty()) { | |
| if (inParagraph) { | |
| *file << "</p>\n"; | |
| inParagraph = false; | |
| } | |
| } else { | |
| if (!inParagraph) { | |
| *file << "<p> "; | |
| inParagraph = true; | |
| } | |
| } | |
| if (!convertDocumentationRefences(&s)) { | |
| return false; | |
| } | |
| *file << s << "\n"; | |
| } | |
| if (inParagraph) { | |
| *file << "</p>\n"; | |
| } | |
| return true; | |
| } | |
| static void writeSummaryTableStart(GeneratedFile* file, const string& label, bool labelIsHeading) { | |
| if (labelIsHeading) { | |
| *file << "<h2 style='margin-bottom: 0px;'>" << label << "</h2>\n"; | |
| } | |
| *file << "<table class='jd-sumtable'><tbody>\n"; | |
| if (!labelIsHeading) { | |
| *file << " <tr><th colspan='2'>" << label << "</th></tr>\n"; | |
| } | |
| } | |
| static void writeSummaryTableEnd(GeneratedFile* file) { | |
| *file << "</tbody></table>\n"; | |
| } | |
| enum DeprecatedSelector { | |
| DEPRECATED_ONLY, | |
| NON_DEPRECATED_ONLY, | |
| ALL, | |
| }; | |
| static void writeSummaryTableEntry(ostream* stream, Definition* definition, | |
| DeprecatedSelector deprecatedSelector) { | |
| if (definition->hidden()) { | |
| return; | |
| } | |
| const bool deprecated = definition->deprecated(); | |
| if ((deprecatedSelector == DEPRECATED_ONLY && !deprecated) || | |
| (deprecatedSelector == NON_DEPRECATED_ONLY && deprecated)) { | |
| return; | |
| } | |
| *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 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, | |
| DeprecatedSelector deprecatedSelector, bool labelAsHeader) { | |
| ostringstream constantStream; | |
| for (auto e : constants) { | |
| writeSummaryTableEntry(&constantStream, e.second, deprecatedSelector); | |
| } | |
| writeSummaryTable(file, &constantStream, "Constants", deprecatedSelector, labelAsHeader); | |
| ostringstream typeStream; | |
| for (auto e : types) { | |
| writeSummaryTableEntry(&typeStream, e.second, deprecatedSelector); | |
| } | |
| writeSummaryTable(file, &typeStream, "Types", deprecatedSelector, labelAsHeader); | |
| ostringstream functionStream; | |
| for (auto e : functions) { | |
| writeSummaryTableEntry(&functionStream, e.second, deprecatedSelector); | |
| } | |
| writeSummaryTable(file, &functionStream, "Functions", deprecatedSelector, labelAsHeader); | |
| } | |
| static void writeHtmlVersionTag(GeneratedFile* file, VersionInfo info, | |
| bool addSpacing) { | |
| ostringstream stream; | |
| if (info.intSize == 32) { | |
| stream << "When compiling for 32 bits. "; | |
| } else if (info.intSize == 64) { | |
| stream << "When compiling for 64 bits. "; | |
| } | |
| if (info.minVersion > 1 || info.maxVersion) { | |
| const char* mid = | |
| "<a " | |
| "href='http://developer.android.com/guide/topics/manifest/" | |
| "uses-sdk-element.html#ApiLevels'>API level "; | |
| if (info.minVersion <= 1) { | |
| // No minimum | |
| if (info.maxVersion > 0) { | |
| stream << "Removed from " << mid << info.maxVersion + 1 << " and higher"; | |
| } | |
| } else { | |
| if (info.maxVersion == 0) { | |
| // No maximum | |
| stream << "Added in " << mid << info.minVersion; | |
| } else { | |
| stream << mid << info.minVersion << " - " << info.maxVersion; | |
| } | |
| } | |
| stream << "</a>"; | |
| } | |
| string s = stream.str(); | |
| // Remove any trailing whitespace | |
| while (s.back() == ' ') { | |
| s.pop_back(); | |
| } | |
| if (!s.empty()) { | |
| *file << (addSpacing ? " " : "") << s << "\n"; | |
| } | |
| } | |
| static void writeDetailedTypeSpecification(GeneratedFile* file, const TypeSpecification* spec) { | |
| switch (spec->getKind()) { | |
| case SIMPLE: { | |
| Type* type = spec->getType(); | |
| *file << "<p>A typedef of: " << spec->getSimpleType() | |
| << makeAttributeTag(spec->getAttribute(), "", type->getDeprecatedApiLevel(), | |
| type->getDeprecatedMessage()) | |
| << " "; | |
| writeHtmlVersionTag(file, spec->getVersionInfo(), false); | |
| *file << "</p>\n"; | |
| break; | |
| } | |
| case RS_OBJECT: { | |
| *file << "<p>"; | |
| writeHtmlVersionTag(file, spec->getVersionInfo(), false); | |
| *file << "</p>\n"; | |
| break; | |
| } | |
| case ENUM: { | |
| *file << "<p>An enum with the following values: \n"; | |
| writeHtmlVersionTag(file, spec->getVersionInfo(), false); | |
| *file << "</p>\n"; | |
| *file << " <table class='jd-tagtable'><tbody>\n"; | |
| const vector<string>& values = spec->getValues(); | |
| const vector<string>& valueComments = spec->getValueComments(); | |
| for (size_t i = 0; i < values.size(); i++) { | |
| *file << " <tr><th>" << values[i] << "</th><td>"; | |
| if (valueComments.size() > i) { | |
| *file << valueComments[i]; | |
| } | |
| *file << "</td></tr>\n"; | |
| } | |
| *file << " </tbody></table><br/>\n"; | |
| break; | |
| } | |
| case STRUCT: { | |
| *file << "<p>A structure with the following fields: "; | |
| writeHtmlVersionTag(file, spec->getVersionInfo(), false); | |
| *file << "</p>\n"; | |
| *file << " <table class='jd-tagtable'><tbody>\n"; | |
| const vector<string>& fields = spec->getFields(); | |
| const vector<string>& fieldComments = spec->getFieldComments(); | |
| for (size_t i = 0; i < fields.size(); i++) { | |
| *file << " <tr><th>" << fields[i] << "</th><td>"; | |
| if (fieldComments.size() > i && !fieldComments[i].empty()) { | |
| *file << fieldComments[i]; | |
| } | |
| *file << "</td></tr>\n"; | |
| } | |
| *file << " </tbody></table><br/>\n"; | |
| break; | |
| } | |
| } | |
| } | |
| static void writeDetailedConstantSpecification(GeneratedFile* file, ConstantSpecification* c) { | |
| *file << " <tr><td>"; | |
| *file << "Value: " << c->getValue() << "\n"; | |
| writeHtmlVersionTag(file, c->getVersionInfo(), true); | |
| *file << " </td></tr>\n"; | |
| *file << "<br/>\n"; | |
| } | |
| static bool writeOverviewForFile(GeneratedFile* file, const SpecFile& specFile) { | |
| bool success = true; | |
| *file << "<h2>" << specFile.getBriefDescription() << "</h2>\n"; | |
| if (!generateHtmlParagraphs(file, specFile.getFullDescription())) { | |
| success = false; | |
| } | |
| // Write the summary tables. | |
| // file << "<h2>Summary</h2>\n"; | |
| writeSummaryTables(file, specFile.getDocumentedConstants(), specFile.getDocumentedTypes(), | |
| specFile.getDocumentedFunctions(), NON_DEPRECATED_ONLY, false); | |
| return success; | |
| } | |
| static bool generateOverview(const string& directory, bool forVerification) { | |
| GeneratedFile file; | |
| if (!file.start(directory, forVerification ? OVERVIEW_HTML_FILE_NAME : OVERVIEW_JD_FILE_NAME)) { | |
| return false; | |
| } | |
| bool success = true; | |
| writeHeader(&file, forVerification, "Runtime API Reference"); | |
| for (auto specFile : systemSpecification.getSpecFiles()) { | |
| if (!writeOverviewForFile(&file, *specFile)) { | |
| success = false; | |
| } | |
| } | |
| writeFooter(&file, forVerification); | |
| file.close(); | |
| return success; | |
| } | |
| static bool generateAlphabeticalIndex(const string& directory, bool forVerification) { | |
| GeneratedFile file; | |
| if (!file.start(directory, forVerification ? INDEX_HTML_FILE_NAME : INDEX_JD_FILE_NAME)) { | |
| return false; | |
| } | |
| writeHeader(&file, forVerification, "Index"); | |
| writeSummaryTables(&file, systemSpecification.getConstants(), systemSpecification.getTypes(), | |
| systemSpecification.getFunctions(), NON_DEPRECATED_ONLY, true); | |
| writeSummaryTables(&file, systemSpecification.getConstants(), systemSpecification.getTypes(), | |
| systemSpecification.getFunctions(), DEPRECATED_ONLY, true); | |
| writeFooter(&file, forVerification); | |
| 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; | |
| } | |
| const string& name = constant->getName(); | |
| *file << "<a name='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"; | |
| *file << " <span class='normal'>: " << constant->getSummary() << "</span>\n"; | |
| *file << " </h4>\n"; | |
| *file << " <div class='jd-details-descr'>\n"; | |
| *file << " <table class='jd-tagtable'><tbody>\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; | |
| } | |
| *file << " </div>\n"; | |
| *file << "</div>\n"; | |
| *file << "\n"; | |
| return true; | |
| } | |
| static bool writeDetailedType(GeneratedFile* file, Type* type) { | |
| if (type->hidden()) { | |
| return true; | |
| } | |
| const string& name = type->getName(); | |
| *file << "<a name='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"; | |
| *file << " <span class='normal'>: " << type->getSummary() << "</span>\n"; | |
| *file << " </h4>\n"; | |
| *file << " <div class='jd-details-descr'>\n"; | |
| for (auto spec : type->getSpecifications()) { | |
| writeDetailedTypeSpecification(file, spec); | |
| } | |
| writeDeprecatedWarning(file, type); | |
| if (!generateHtmlParagraphs(file, type->getDescription())) { | |
| return false; | |
| } | |
| *file << " </div>\n"; | |
| *file << "</div>\n"; | |
| *file << "\n"; | |
| return true; | |
| } | |
| static bool writeDetailedFunction(GeneratedFile* file, Function* function) { | |
| if (function->hidden()) { | |
| return true; | |
| } | |
| const string& name = function->getName(); | |
| *file << "<a name='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"; | |
| *file << " <span class='normal'>: " << function->getSummary() << "</span>\n"; | |
| *file << " </h4>\n"; | |
| *file << " <div class='jd-details-descr'>\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>"; | |
| writeHtmlVersionTag(file, i.second.info, true); | |
| *file << " </td>\n"; | |
| *file << " </tr>\n"; | |
| } | |
| *file << " </tbody></table>\n"; | |
| *file << " </div>\n"; | |
| if (function->someParametersAreDocumented()) { | |
| *file << " <div class='jd-tagdata'>"; | |
| *file << " <h5 class='jd-tagtitle'>Parameters</h5>\n"; | |
| *file << " <table class='jd-tagtable'><tbody>\n"; | |
| for (ParameterEntry* p : function->getParameters()) { | |
| *file << " <tr><th>" << p->name << "</th><td>" << p->documentation << "</td></tr>\n"; | |
| } | |
| *file << " </tbody></table>\n"; | |
| *file << " </div>\n"; | |
| } | |
| string ret = function->getReturnDocumentation(); | |
| if (!ret.empty()) { | |
| *file << " <div class='jd-tagdata'>"; | |
| *file << " <h5 class='jd-tagtitle'>Returns</h5>\n"; | |
| *file << " <table class='jd-tagtable'><tbody>\n"; | |
| *file << " <tr><td>" << ret << "</td></tr>\n"; | |
| *file << " </tbody></table>\n"; | |
| *file << " </div>\n"; | |
| } | |
| *file << " <div class='jd-tagdata jd-tagdescr'>\n"; | |
| writeDeprecatedWarning(file, function); | |
| if (!generateHtmlParagraphs(file, function->getDescription())) { | |
| return false; | |
| } | |
| *file << " </div>\n"; | |
| *file << "</div>\n"; | |
| *file << "\n"; | |
| return true; | |
| } | |
| static bool writeDetailedDocumentationFile(const string& directory, const SpecFile& specFile, | |
| bool forVerification) { | |
| if (!specFile.hasSpecifications()) { | |
| // This is true for rs_core.spec | |
| return true; | |
| } | |
| GeneratedFile file; | |
| const string fileName = stringReplace(specFile.getSpecFileName(), ".spec", | |
| forVerification ? ".html" : ".jd"); | |
| if (!file.start(directory, fileName)) { | |
| return false; | |
| } | |
| bool success = true; | |
| string title = specFile.getBriefDescription(); | |
| writeHeader(&file, forVerification, title); | |
| file << "<h2>Overview</h2>\n"; | |
| if (!generateHtmlParagraphs(&file, specFile.getFullDescription())) { | |
| success = false; | |
| } | |
| // Write the summary tables. | |
| file << "<h2>Summary</h2>\n"; | |
| const auto& constants = specFile.getDocumentedConstants(); | |
| const auto& types = specFile.getDocumentedTypes(); | |
| const auto& functions = specFile.getDocumentedFunctions(); | |
| 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()) { | |
| file << "<h2>Constants</h2>\n"; | |
| for (auto i : constants) { | |
| if (!writeDetailedConstant(&file, i.second)) { | |
| success = false; | |
| } | |
| } | |
| } | |
| if (!types.empty()) { | |
| file << "<h2>Types</h2>\n"; | |
| for (auto i : types) { | |
| if (!writeDetailedType(&file, i.second)) { | |
| success = false; | |
| } | |
| } | |
| } | |
| if (!functions.empty()) { | |
| file << "<h2>Functions</h2>\n"; | |
| for (auto i : functions) { | |
| if (!writeDetailedFunction(&file, i.second)) { | |
| success = false; | |
| } | |
| } | |
| } | |
| writeFooter(&file, forVerification); | |
| file.close(); | |
| if (!success) { | |
| // If in error, write a final message to make it easier to figure out which file failed. | |
| cerr << fileName << ": Failed due to errors.\n"; | |
| } | |
| return success; | |
| } | |
| static void generateSnippet(GeneratedFile* file, const string& fileName, const string& title) { | |
| const char offset[] = " "; | |
| *file << offset << "<li><a href=\"<?cs var:toroot ?>guide/topics/renderscript/reference/" | |
| << fileName << "\">\n"; | |
| *file << offset << " <span class=\"en\">" << title << "</span>\n"; | |
| *file << offset << "</a></li>\n"; | |
| } | |
| /* Generate a partial file of links that should be cut & pasted into the proper section of the | |
| * guide_toc.cs file. | |
| */ | |
| static bool generateAndroidTableOfContentSnippet(const string& directory) { | |
| GeneratedFile file; | |
| if (!file.start(directory, "guide_toc.cs")) { | |
| return false; | |
| } | |
| file << "<!-- Copy and paste the following lines into the RenderScript section of\n"; | |
| file << " platform/frameworks/base/docs/html/guide/guide_toc.cs\n\n"; | |
| const char offset[] = " "; | |
| file << offset << "<li class=\"nav-section\">\n"; | |
| file << offset << " <div class=\"nav-section-header\">\n"; | |
| file << offset << " <a href=\"<?cs var:toroot ?>guide/topics/renderscript/reference/" << | |
| OVERVIEW_HTML_FILE_NAME << "\">\n"; | |
| file << offset << " <span class=\"en\">Runtime API Reference</span>\n"; | |
| file << offset << " </a></div>\n"; | |
| file << offset << " <ul>\n"; | |
| for (auto specFile : systemSpecification.getSpecFiles()) { | |
| if (specFile->hasSpecifications()) { | |
| const string fileName = stringReplace(specFile->getSpecFileName(), ".spec", ".html"); | |
| generateSnippet(&file, fileName, specFile->getBriefDescription()); | |
| } | |
| } | |
| generateSnippet(&file, INDEX_HTML_FILE_NAME, "Index"); | |
| file << offset << " </ul>\n"; | |
| file << offset << "</li>\n"; | |
| return true; | |
| } | |
| bool generateDocumentation(const string& directory, bool forVerification) { | |
| bool success = generateOverview(directory, forVerification) && | |
| generateAlphabeticalIndex(directory, forVerification) && | |
| generateAndroidTableOfContentSnippet(directory); | |
| for (auto specFile : systemSpecification.getSpecFiles()) { | |
| if (!writeDetailedDocumentationFile(directory, *specFile, forVerification)) { | |
| success = false; | |
| } | |
| } | |
| return success; | |
| } |