/* * 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 #include #include #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 INDEX_HTML_FILE_NAME[] = "index.html"; static void writeHeader(GeneratedFile* file, const string& title, const SpecFile& specFile) { // Generate DevSite markups *file << "\n" "\n" "\n" " RenderScript " << title << "\n" " \n" " \n" " \n" " \n"; auto desc = specFile.getFullDescription(); if (desc.size()) { *file << " \n"; } *file << "\n\n" "\n\n"; *file << "
\n"; } static void writeFooter(GeneratedFile* file) { *file << "
\n"; *file << "\n\n\n"; *file << "\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* 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(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& description) { bool inParagraph = false; for (auto s : description) { // Empty lines in the .spec marks paragraphs. if (s.empty()) { if (inParagraph) { *file << "

\n"; inParagraph = false; } } else { if (!inParagraph) { *file << "

"; inParagraph = true; } } if (!convertDocumentationRefences(&s)) { return false; } *file << s << "\n"; } if (inParagraph) { *file << "

\n"; } return true; } static void writeSummaryTableStart(GeneratedFile* file, const string& label, bool labelIsHeading) { if (labelIsHeading) { *file << "

" << label << "

\n"; } *file << "\n"; if (!labelIsHeading) { *file << " \n"; } } static void writeSummaryTableEnd(GeneratedFile* file) { *file << "
" << label << "
\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 << " \n"; *stream << " \n"; *stream << " " << definition->getName() << "\n"; *stream << " \n"; *stream << " \n"; *stream << " "; if (deprecated) { *stream << "Deprecated. "; } *stream << definition->getSummary() << "\n"; *stream << " \n"; *stream << " \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& constants, const map& types, const map& 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 = "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 << ""; } 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 << "

A typedef of: " << spec->getSimpleType() << makeAttributeTag(spec->getAttribute(), "", type->getDeprecatedApiLevel(), type->getDeprecatedMessage()) << "     "; writeHtmlVersionTag(file, spec->getVersionInfo(), false); *file << "

\n"; break; } case RS_OBJECT: { *file << "

"; writeHtmlVersionTag(file, spec->getVersionInfo(), false); *file << "

\n"; break; } case ENUM: { *file << "

An enum with the following values:     \n"; writeHtmlVersionTag(file, spec->getVersionInfo(), false); *file << "

\n"; *file << " \n"; const vector& values = spec->getValues(); const vector& valueComments = spec->getValueComments(); for (size_t i = 0; i < values.size(); i++) { *file << " \n"; } *file << "
" << values[i] << ""; if (valueComments.size() > i) { *file << valueComments[i]; } *file << "

\n"; break; } case STRUCT: { *file << "

A structure with the following fields:     "; writeHtmlVersionTag(file, spec->getVersionInfo(), false); *file << "

\n"; *file << " \n"; const vector& fields = spec->getFields(); const vector& fieldComments = spec->getFieldComments(); for (size_t i = 0; i < fields.size(); i++) { *file << " \n"; } *file << "
" << fields[i] << ""; if (fieldComments.size() > i && !fieldComments[i].empty()) { *file << fieldComments[i]; } *file << "

\n"; break; } } } static void writeDetailedConstantSpecification(GeneratedFile* file, ConstantSpecification* c) { *file << " "; *file << "Value: " << c->getValue() << "\n"; writeHtmlVersionTag(file, c->getVersionInfo(), true); *file << " \n"; *file << "
\n"; } static bool writeOverviewForFile(GeneratedFile* file, const SpecFile& specFile) { bool success = true; *file << "

" << specFile.getBriefDescription() << "

\n"; if (!generateHtmlParagraphs(file, specFile.getFullDescription())) { success = false; } // Write the summary tables. // file << "

Summary

\n"; writeSummaryTables(file, specFile.getDocumentedConstants(), specFile.getDocumentedTypes(), specFile.getDocumentedFunctions(), NON_DEPRECATED_ONLY, false); return success; } static bool generateOverview(const string& directory) { GeneratedFile file; if (!file.start(directory, OVERVIEW_HTML_FILE_NAME)) { return false; } bool success = true; // Take the description from the first spec file (rs_core.spec, based on how // currently this generator is called) writeHeader(&file, "Runtime API Reference", *(systemSpecification.getSpecFiles()[0])); for (auto specFile : systemSpecification.getSpecFiles()) { if (!writeOverviewForFile(&file, *specFile)) { success = false; } } writeFooter(&file); file.close(); return success; } static bool generateAlphabeticalIndex(const string& directory) { GeneratedFile file; if (!file.start(directory, INDEX_HTML_FILE_NAME)) { return false; } writeHeader(&file, "Index", SpecFile("")); 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); file.close(); return true; } static void writeDeprecatedWarning(GeneratedFile* file, Definition* definition) { if (definition->deprecated()) { *file << "

Deprecated. "; string s = definition->getDeprecatedMessage(); convertDocumentationRefences(&s); if (!s.empty()) { *file << s; } else { *file << "Do not use."; } *file << "

\n"; } } static bool writeDetailedConstant(GeneratedFile* file, Constant* constant) { if (constant->hidden()) { return true; } const string& name = constant->getName(); *file << "\n"; *file << "
\n"; *file << "

\n"; *file << " " << name << "\n"; *file << " : " << constant->getSummary() << "\n"; *file << "

\n"; *file << "
\n"; *file << " \n"; auto specifications = constant->getSpecifications(); bool addSeparator = specifications.size() > 1; for (auto spec : specifications) { if (addSeparator) { *file << "
Variant:
\n"; } writeDetailedConstantSpecification(file, spec); } *file << "
\n"; *file << "
\n"; *file << "
\n"; writeDeprecatedWarning(file, constant); if (!generateHtmlParagraphs(file, constant->getDescription())) { return false; } *file << "
\n"; *file << "
\n"; *file << "\n"; return true; } static bool writeDetailedType(GeneratedFile* file, Type* type) { if (type->hidden()) { return true; } const string& name = type->getName(); *file << "\n"; *file << "
\n"; *file << "

\n"; *file << " " << name << "\n"; *file << " : " << type->getSummary() << "\n"; *file << "

\n"; *file << "
\n"; for (auto spec : type->getSpecifications()) { writeDetailedTypeSpecification(file, spec); } writeDeprecatedWarning(file, type); if (!generateHtmlParagraphs(file, type->getDescription())) { return false; } *file << "
\n"; *file << "
\n"; *file << "\n"; return true; } static bool writeDetailedFunction(GeneratedFile* file, Function* function) { if (function->hidden()) { return true; } const string& name = function->getName(); *file << "\n"; *file << "
\n"; *file << "

\n"; *file << " " << name << "\n"; *file << " : " << function->getSummary() << "\n"; *file << "

\n"; *file << "
\n"; map entries; if (!getUnifiedFunctionPrototypes(function, &entries)) { return false; } *file << " \n"; for (auto i : entries) { *file << " \n"; *file << " \n"; *file << " \n"; *file << " \n"; } *file << "
" << i.second.htmlDeclaration << ""; writeHtmlVersionTag(file, i.second.info, true); *file << "
\n"; *file << "
\n"; if (function->someParametersAreDocumented()) { *file << "
"; *file << "
Parameters
\n"; *file << " \n"; for (ParameterEntry* p : function->getParameters()) { *file << " \n"; } *file << "
" << p->name << "" << p->documentation << "
\n"; *file << "
\n"; } string ret = function->getReturnDocumentation(); if (!ret.empty()) { *file << "
"; *file << "
Returns
\n"; *file << " \n"; *file << " \n"; *file << "
" << ret << "
\n"; *file << "
\n"; } *file << "
\n"; writeDeprecatedWarning(file, function); if (!generateHtmlParagraphs(file, function->getDescription())) { return false; } *file << "
\n"; *file << "
\n"; *file << "\n"; return true; } static bool writeDetailedDocumentationFile(const string& directory, const SpecFile& specFile) { if (!specFile.hasSpecifications()) { // This is true for rs_core.spec return true; } GeneratedFile file; const string fileName = stringReplace(specFile.getSpecFileName(), ".spec", ".html"); if (!file.start(directory, fileName)) { return false; } bool success = true; string title = specFile.getBriefDescription(); writeHeader(&file, title, specFile); file << "

Overview

\n"; if (!generateHtmlParagraphs(&file, specFile.getFullDescription())) { success = false; } // Write the summary tables. file << "

Summary

\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 << "

Constants

\n"; for (auto i : constants) { if (!writeDetailedConstant(&file, i.second)) { success = false; } } } if (!types.empty()) { file << "

Types

\n"; for (auto i : types) { if (!writeDetailedType(&file, i.second)) { success = false; } } } if (!functions.empty()) { file << "

Functions

\n"; for (auto i : functions) { if (!writeDetailedFunction(&file, i.second)) { success = false; } } } writeFooter(&file); 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 << "
  • guide/topics/renderscript/reference/" << fileName << "\">\n"; *file << offset << " " << title << "\n"; *file << offset << "
    • \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 << "