Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / frameworks / rs / ffc1710c382168e74386ef87d0101de65aca91b0 / . / api / GenerateDocumentation.cpp
blob: 9d399d4ee933e3366e184afbfbbf6cba9f333eca [file] [log] [blame]
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]1/*
2 * Copyright (C) 2015 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17#include <iostream>
18#include <sstream>
19
20#include "Generator.h"
21#include "Specification.h"
22#include "Utilities.h"
23
24using namespace std;
25
26struct DetailedFunctionEntry {
27 VersionInfo info;
28 string htmlDeclaration;
29};
30
Jean-Luc Brouillet2217eb72015-04-24 14:41:48 -0700[diff] [blame]31static const char OVERVIEW_HTML_FILE_NAME[] = "overview.html";
32static const char OVERVIEW_JD_FILE_NAME[] = "overview.jd";
33static const char INDEX_HTML_FILE_NAME[] = "index.html";
34static const char INDEX_JD_FILE_NAME[] = "index.jd";
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]35
Jean-Luc Brouillet2217eb72015-04-24 14:41:48 -0700[diff] [blame]36static void writeHeader(GeneratedFile* file, bool forVerification, const string& title) {
37 if (forVerification) {
38 *file << "<!DOCTYPE html>\n";
39 *file << "<!-- " << AUTO_GENERATED_WARNING << "-->\n";
Jean-Luc Brouillet6386ceb2015-04-28 15:06:30 -0700[diff] [blame]40 *file << "<html><head>\n"
41 "<title>RenderScript Reference</title>\n"
42 "<meta http-equiv='Content-Type' content='text/html; charset=UTF-8'>\n"
Jean-Luc Brouillet2217eb72015-04-24 14:41:48 -0700[diff] [blame]43 "<link rel='stylesheet' "
44 "href='http://fonts.googleapis.com/css?family=Roboto+Condensed'>\n"
45 "<link rel='stylesheet' href='http://fonts.googleapis.com/"
46 "css?family=Roboto:light,regular,medium,thin,italic,mediumitalic,bold' "
47 "title='roboto'>\n"
Jean-Luc Brouillet6386ceb2015-04-28 15:06:30 -0700[diff] [blame]48 "<link href='default.css' rel='stylesheet' type='text/css'>\n"
49 "<link href='fullscreen.css' rel='stylesheet' class='fullscreen' "
Jean-Luc Brouillet2217eb72015-04-24 14:41:48 -0700[diff] [blame]50 "type='text/css'>\n"
Jean-Luc Brouillet6386ceb2015-04-28 15:06:30 -0700[diff] [blame]51 "<body class='gc-documentation develop reference'>\n\n";
Jean-Luc Brouillet2217eb72015-04-24 14:41:48 -0700[diff] [blame]52 *file << "<h1>" << title << "</h1>\n";
53 } else {
54 *file << "page.title=RenderScript " << title << "\n\n";
55 *file << "@jd:body\n\n";
56 }
Jean-Luc Brouillet918944e2015-04-30 11:12:40 -0700[diff] [blame]57 *file << "<div class='renderscript'>\n";
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]58}
59
Jean-Luc Brouillet2217eb72015-04-24 14:41:48 -0700[diff] [blame]60static void writeFooter(GeneratedFile* file, bool forVerification) {
Jean-Luc Brouillet918944e2015-04-30 11:12:40 -0700[diff] [blame]61 *file << "</div>\n";
Jean-Luc Brouillet2217eb72015-04-24 14:41:48 -0700[diff] [blame]62 if (forVerification) {
Jean-Luc Brouillet6386ceb2015-04-28 15:06:30 -0700[diff] [blame]63 *file << "</body></html>\n";
Jean-Luc Brouillet2217eb72015-04-24 14:41:48 -0700[diff] [blame]64 }
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]65}
66
67// If prefix starts input, copy it to stream and remove it from input.
68static void skipPrefix(ostringstream* stream, string* input, const string& prefix) {
69 size_t size = prefix.size();
70 if (input->compare(0, size, prefix) != 0) {
71 return;
72 }
73 input->erase(0, size);
74 *stream << prefix;
75}
76
77// Merge b into a. Returns true if successful
78static bool mergeVersionInfo(VersionInfo* a, const VersionInfo& b) {
79 if (a->intSize != b.intSize) {
80 cerr << "Error. We don't currently support versions that differ based on int size\n";
81 return false;
82 }
83 if (b.minVersion != 0 && a->maxVersion == b.minVersion - 1) {
84 a->maxVersion = b.maxVersion;
85 } else if (b.maxVersion != 0 && a->minVersion == b.maxVersion + 1) {
86 a->minVersion = b.minVersion;
87 } else {
88 cerr << "Error. This code currently assume that all versions are contiguous. Don't know "
89 "how to merge versions (" << a->minVersion << " - " << a->maxVersion << ") and ("
90 << b.minVersion << " - " << b.maxVersion << ")\n";
91 return false;
92 }
93 return true;
94}
95
96static string getHtmlStringForType(const ParameterDefinition& parameter) {
97 string s = parameter.rsType;
98 ostringstream stream;
99 skipPrefix(&stream, &s, "const ");
100 skipPrefix(&stream, &s, "volatile ");
101 bool endsWithAsterisk = s.size() > 0 && s[s.size() - 1] == '*';
102 if (endsWithAsterisk) {
103 s.erase(s.size() - 1, 1);
104 }
105
106 string anchor = systemSpecification.getHtmlAnchor(s);
107 if (anchor.empty()) {
108 // Not a RenderScript specific type.
109 return parameter.rsType;
110 } else {
111 stream << anchor;
112 }
113 if (endsWithAsterisk) {
114 stream << "*";
115 }
116 return stream.str();
117}
118
119static string getDetailedHtmlDeclaration(const FunctionPermutation& permutation) {
120 ostringstream stream;
121 auto ret = permutation.getReturn();
122 if (ret) {
123 stream << getHtmlStringForType(*ret);
124 } else {
125 stream << "void";
126 }
127 stream << " " << permutation.getName() << "(";
128 bool needComma = false;
129 for (auto p : permutation.getParams()) {
130 if (needComma) {
131 stream << ", ";
132 }
133 stream << getHtmlStringForType(*p);
134 if (p->isOutParameter) {
135 stream << "*";
136 }
137 if (!p->specName.empty()) {
138 stream << " " << p->specName;
139 }
140 needComma = true;
141 }
142 stream << ");\n";
143 return stream.str();
144}
145
146/* Some functions (like max) have changed implementations but not their
147 * declaration. We need to unify these so that we don't end up with entries
148 * like:
149 * char max(char a, char b); Removed from API level 20
150 * char max(char a, char b); Added to API level 20
151 */
152static bool getUnifiedFunctionPrototypes(Function* function,
153 map<string, DetailedFunctionEntry>* entries) {
154 for (auto f : function->getSpecifications()) {
155 DetailedFunctionEntry entry;
156 entry.info = f->getVersionInfo();
157 for (auto p : f->getPermutations()) {
158 entry.htmlDeclaration = getDetailedHtmlDeclaration(*p);
159 const string s = stripHtml(entry.htmlDeclaration);
160 auto i = entries->find(s);
161 if (i == entries->end()) {
162 entries->insert(pair<string, DetailedFunctionEntry>(s, entry));
163 } else {
164 if (!mergeVersionInfo(&i->second.info, entry.info)) {
165 return false;
166 }
167 }
168 }
169 }
170 return true;
171}
172
173// Convert words starting with @ into HTML references. Returns false if error.
174static bool convertDocumentationRefences(string* s) {
175 bool success = true;
176 size_t end = 0;
177 for (;;) {
178 size_t start = s->find('@', end);
179 if (start == string::npos) {
180 break;
181 }
182 // Find the end of the identifier
183 end = start;
184 char c;
185 do {
186 c = (*s)[++end];
187 } while (isalnum(c) || c == '_');
188
189 const string id = s->substr(start + 1, end - start - 1);
190 string anchor = systemSpecification.getHtmlAnchor(id);
191 if (anchor.empty()) {
192 cerr << "Error: Can't convert the documentation reference @" << id << "\n";
193 success = false;
194 }
195 s->replace(start, end - start, anchor);
196 }
197 return success;
198}
199
200static bool generateHtmlParagraphs(GeneratedFile* file, const vector<string>& description) {
201 bool inParagraph = false;
202 for (auto s : description) {
203 // Empty lines in the .spec marks paragraphs.
204 if (s.empty()) {
205 if (inParagraph) {
206 *file << "</p>\n";
207 inParagraph = false;
208 }
209 } else {
210 if (!inParagraph) {
211 *file << "<p> ";
212 inParagraph = true;
213 }
214 }
215 if (!convertDocumentationRefences(&s)) {
216 return false;
217 }
218 *file << s << "\n";
219 }
220 if (inParagraph) {
221 *file << "</p>\n";
222 }
223 return true;
224}
225
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]226static void writeSummaryTableStart(GeneratedFile* file, const string& label, bool labelIsHeading) {
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]227 if (labelIsHeading) {
Jean-Luc Brouillet6386ceb2015-04-28 15:06:30 -0700[diff] [blame]228 *file << "<h2 style='margin-bottom: 0px;'>" << label << "</h2>\n";
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]229 }
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]230 *file << "<table class='jd-sumtable'><tbody>\n";
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]231 if (!labelIsHeading) {
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]232 *file << " <tr><th colspan='2'>" << label << "</th></tr>\n";
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]233 }
234}
235
236static void writeSummaryTableEnd(GeneratedFile* file) {
237 *file << "</tbody></table>\n";
238}
239
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]240enum DeprecatedSelector {
241 DEPRECATED_ONLY,
242 NON_DEPRECATED_ONLY,
243 ALL,
244};
245
246static void writeSummaryTableEntry(ostream* stream, Definition* definition,
247 DeprecatedSelector deprecatedSelector) {
248 if (definition->hidden()) {
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]249 return;
250 }
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]251 const bool deprecated = definition->deprecated();
252 if ((deprecatedSelector == DEPRECATED_ONLY && !deprecated) ||
253 (deprecatedSelector == NON_DEPRECATED_ONLY && deprecated)) {
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]254 return;
255 }
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]256
257 *stream << " <tr class='alt-color api apilevel-1'>\n";
258 *stream << " <td class='jd-linkcol'>\n";
Jean-Luc Brouillet2217eb72015-04-24 14:41:48 -0700[diff] [blame]259 *stream << " <a href='" << definition->getUrl() << "'>" << definition->getName()
260 << "</a>\n";
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]261 *stream << " </td>\n";
262 *stream << " <td class='jd-descrcol' width='100%'>\n";
263 *stream << " ";
264 if (deprecated) {
265 *stream << "<b>Deprecated</b>. ";
266 }
267 *stream << definition->getSummary() << "\n";
268 *stream << " </td>\n";
269 *stream << " </tr>\n";
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]270}
271
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]272static void writeSummaryTable(GeneratedFile* file, const ostringstream* entries, const char* name,
273 DeprecatedSelector deprecatedSelector, bool labelAsHeader) {
274 string s = entries->str();
275 if (!s.empty()) {
276 string prefix;
277 if (deprecatedSelector == DEPRECATED_ONLY) {
278 prefix = "Deprecated ";
279 }
280 writeSummaryTableStart(file, prefix + name, labelAsHeader);
281 *file << s;
282 writeSummaryTableEnd(file);
283 }
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]284}
285
286static void writeSummaryTables(GeneratedFile* file, const map<string, Constant*>& constants,
287 const map<string, Type*>& types,
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]288 const map<string, Function*>& functions,
289 DeprecatedSelector deprecatedSelector, bool labelAsHeader) {
290 ostringstream constantStream;
291 for (auto e : constants) {
292 writeSummaryTableEntry(&constantStream, e.second, deprecatedSelector);
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]293 }
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]294 writeSummaryTable(file, &constantStream, "Constants", deprecatedSelector, labelAsHeader);
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]295
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]296 ostringstream typeStream;
297 for (auto e : types) {
298 writeSummaryTableEntry(&typeStream, e.second, deprecatedSelector);
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]299 }
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]300 writeSummaryTable(file, &typeStream, "Types", deprecatedSelector, labelAsHeader);
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]301
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]302 ostringstream functionStream;
303 for (auto e : functions) {
304 writeSummaryTableEntry(&functionStream, e.second, deprecatedSelector);
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]305 }
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]306 writeSummaryTable(file, &functionStream, "Functions", deprecatedSelector, labelAsHeader);
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]307}
308
309static void writeHtmlVersionTag(GeneratedFile* file, VersionInfo info) {
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]310 ostringstream stream;
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]311 if (info.intSize == 32) {
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]312 stream << "When compiling for 32 bits. ";
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]313 } else if (info.intSize == 64) {
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]314 stream << "When compiling for 64 bits. ";
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]315 }
316
317 if (info.minVersion > 1 || info.maxVersion) {
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]318 const char* mid =
319 "<a "
320 "href='http://developer.android.com/guide/topics/manifest/"
321 "uses-sdk-element.html#ApiLevels'>API level ";
322 if (info.minVersion <= 1) {
323 // No minimum
324 if (info.maxVersion > 0) {
Jean-Luc Brouilletffc17102015-08-13 22:47:06 -0700[diff] [blame^]325 stream << "Removed from " << mid << info.maxVersion + 1 << " and higher";
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]326 }
327 } else {
328 if (info.maxVersion == 0) {
329 // No maximum
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]330 stream << "Added in " << mid << info.minVersion;
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]331 } else {
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]332 stream << mid << info.minVersion << " - " << info.maxVersion;
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]333 }
334 }
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]335 stream << "</a>";
336 }
337 const string s = stream.str();
338 if (!s.empty()) {
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]339 *file << " " << s << "\n";
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]340 }
341}
342
Jean-Luc Brouillet36e2be52015-04-30 14:41:24 -0700[diff] [blame]343static void writeDetailedTypeSpecification(GeneratedFile* file, const TypeSpecification* spec) {
344 switch (spec->getKind()) {
345 case SIMPLE: {
346 Type* type = spec->getType();
347 *file << "<p>A typedef of: " << spec->getSimpleType()
348 << makeAttributeTag(spec->getAttribute(), "", type->deprecated(),
349 type->getDeprecatedMessage())
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]350 << "&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;";
Jean-Luc Brouillet36e2be52015-04-30 14:41:24 -0700[diff] [blame]351 writeHtmlVersionTag(file, spec->getVersionInfo());
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]352 *file << "</p>\n";
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]353 break;
Jean-Luc Brouillet36e2be52015-04-30 14:41:24 -0700[diff] [blame]354 }
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]355 case ENUM: {
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]356 *file << "<p>An enum with the following values:&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\n";
Jean-Luc Brouillet36e2be52015-04-30 14:41:24 -0700[diff] [blame]357 writeHtmlVersionTag(file, spec->getVersionInfo());
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]358 *file << "</p>\n";
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]359
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]360 *file << " <table class='jd-tagtable'><tbody>\n";
Jean-Luc Brouillet36e2be52015-04-30 14:41:24 -0700[diff] [blame]361 const vector<string>& values = spec->getValues();
362 const vector<string>& valueComments = spec->getValueComments();
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]363 for (size_t i = 0; i < values.size(); i++) {
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]364 *file << " <tr><th>" << values[i] << "</th><td>";
365 if (valueComments.size() > i) {
366 *file << valueComments[i];
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]367 }
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]368 *file << "</td></tr>\n";
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]369 }
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]370 *file << " </tbody></table><br/>\n";
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]371 break;
372 }
373 case STRUCT: {
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]374 *file << "<p>A structure with the following fields:&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;";
Jean-Luc Brouillet36e2be52015-04-30 14:41:24 -0700[diff] [blame]375 writeHtmlVersionTag(file, spec->getVersionInfo());
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]376 *file << "</p>\n";
377
378 *file << " <table class='jd-tagtable'><tbody>\n";
Jean-Luc Brouillet36e2be52015-04-30 14:41:24 -0700[diff] [blame]379 const vector<string>& fields = spec->getFields();
380 const vector<string>& fieldComments = spec->getFieldComments();
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]381 for (size_t i = 0; i < fields.size(); i++) {
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]382 *file << " <tr><th>" << fields[i] << "</th><td>";
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]383 if (fieldComments.size() > i && !fieldComments[i].empty()) {
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]384 *file << fieldComments[i];
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]385 }
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]386 *file << "</td></tr>\n";
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]387 }
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]388 *file << " </tbody></table><br/>\n";
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]389 break;
390 }
391 }
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]392}
393
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]394static void writeDetailedConstantSpecification(GeneratedFile* file, ConstantSpecification* c) {
395 *file << " <tr><td>";
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]396 *file << "Value: " << c->getValue() << "\n";
397 writeHtmlVersionTag(file, c->getVersionInfo());
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]398 *file << " </td></tr>\n";
399 *file << "<br/>\n";
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]400}
401
402static bool writeOverviewForFile(GeneratedFile* file, const SpecFile& specFile) {
403 bool success = true;
404 *file << "<h2>" << specFile.getBriefDescription() << "</h2>\n";
405 if (!generateHtmlParagraphs(file, specFile.getFullDescription())) {
406 success = false;
407 }
408
409 // Write the summary tables.
410 // file << "<h2>Summary</h2>\n";
Jean-Luc Brouillet7c078542015-03-23 16:16:08 -0700[diff] [blame]411 writeSummaryTables(file, specFile.getDocumentedConstants(), specFile.getDocumentedTypes(),
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]412 specFile.getDocumentedFunctions(), NON_DEPRECATED_ONLY, false);
413
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]414 return success;
415}
416
Jean-Luc Brouillet2217eb72015-04-24 14:41:48 -0700[diff] [blame]417static bool generateOverview(const string& directory, bool forVerification) {
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]418 GeneratedFile file;
Jean-Luc Brouillet2217eb72015-04-24 14:41:48 -0700[diff] [blame]419 if (!file.start(directory, forVerification ? OVERVIEW_HTML_FILE_NAME : OVERVIEW_JD_FILE_NAME)) {
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]420 return false;
421 }
422 bool success = true;
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]423
Jean-Luc Brouillet6386ceb2015-04-28 15:06:30 -0700[diff] [blame]424 writeHeader(&file, forVerification, "Runtime API Reference");
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]425
426 for (auto specFile : systemSpecification.getSpecFiles()) {
427 if (!writeOverviewForFile(&file, *specFile)) {
428 success = false;
429 }
430 }
431
Jean-Luc Brouillet2217eb72015-04-24 14:41:48 -0700[diff] [blame]432 writeFooter(&file, forVerification);
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]433 file.close();
434 return success;
435}
436
Jean-Luc Brouillet2217eb72015-04-24 14:41:48 -0700[diff] [blame]437static bool generateAlphabeticalIndex(const string& directory, bool forVerification) {
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]438 GeneratedFile file;
Jean-Luc Brouillet2217eb72015-04-24 14:41:48 -0700[diff] [blame]439 if (!file.start(directory, forVerification ? INDEX_HTML_FILE_NAME : INDEX_JD_FILE_NAME)) {
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]440 return false;
441 }
Jean-Luc Brouillet2217eb72015-04-24 14:41:48 -0700[diff] [blame]442 writeHeader(&file, forVerification, "Index");
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]443
444 writeSummaryTables(&file, systemSpecification.getConstants(), systemSpecification.getTypes(),
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]445 systemSpecification.getFunctions(), NON_DEPRECATED_ONLY, true);
446
447 writeSummaryTables(&file, systemSpecification.getConstants(), systemSpecification.getTypes(),
448 systemSpecification.getFunctions(), DEPRECATED_ONLY, true);
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]449
Jean-Luc Brouillet2217eb72015-04-24 14:41:48 -0700[diff] [blame]450 writeFooter(&file, forVerification);
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]451 file.close();
452 return true;
453}
454
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]455static void writeDeprecatedWarning(GeneratedFile* file, Definition* definition) {
456 if (definition->deprecated()) {
457 *file << " <p><b>Deprecated.</b> ";
458 string s = definition->getDeprecatedMessage();
459 convertDocumentationRefences(&s);
460 if (!s.empty()) {
461 *file << s;
462 } else {
463 *file << "Do not use.";
464 }
465 *file << "</p>\n";
466 }
467}
468
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]469static bool writeDetailedConstant(GeneratedFile* file, Constant* constant) {
470 if (constant->hidden()) {
471 return true;
472 }
473 const string& name = constant->getName();
474
Jean-Luc Brouillet918944e2015-04-30 11:12:40 -0700[diff] [blame]475 *file << "<a name='android_rs:" << name << "'></a>\n";
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]476 *file << "<div class='jd-details'>\n";
477 *file << " <h4 class='jd-details-title'>\n";
478 *file << " <span class='sympad'>" << name << "</span>\n";
479 *file << " <span class='normal'>: " << constant->getSummary() << "</span>\n";
480 *file << " </h4>\n";
481
482 *file << " <div class='jd-details-descr'>\n";
483 *file << " <table class='jd-tagtable'><tbody>\n";
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]484 auto specifications = constant->getSpecifications();
485 bool addSeparator = specifications.size() > 1;
486 for (auto spec : specifications) {
487 if (addSeparator) {
488 *file << " <h5 class='jd-tagtitle'>Variant:</h5>\n";
489 }
490 writeDetailedConstantSpecification(file, spec);
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]491 }
492 *file << " </tbody></table>\n";
493 *file << " </div>\n";
494
495 *file << " <div class='jd-tagdata jd-tagdescr'>\n";
496
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]497 writeDeprecatedWarning(file, constant);
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]498 if (!generateHtmlParagraphs(file, constant->getDescription())) {
499 return false;
500 }
501 *file << " </div>\n";
502
503 *file << "</div>\n";
504 *file << "\n";
505 return true;
506}
507
508static bool writeDetailedType(GeneratedFile* file, Type* type) {
509 if (type->hidden()) {
510 return true;
511 }
512 const string& name = type->getName();
513
Jean-Luc Brouillet918944e2015-04-30 11:12:40 -0700[diff] [blame]514 *file << "<a name='android_rs:" << name << "'></a>\n";
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]515 *file << "<div class='jd-details'>\n";
516 *file << " <h4 class='jd-details-title'>\n";
517 *file << " <span class='sympad'>" << name << "</span>\n";
518 *file << " <span class='normal'>: " << type->getSummary() << "</span>\n";
519 *file << " </h4>\n";
520
521 *file << " <div class='jd-details-descr'>\n";
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]522 for (auto spec : type->getSpecifications()) {
523 writeDetailedTypeSpecification(file, spec);
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]524 }
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]525
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]526 writeDeprecatedWarning(file, type);
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]527 if (!generateHtmlParagraphs(file, type->getDescription())) {
528 return false;
529 }
530
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]531 *file << " </div>\n";
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]532 *file << "</div>\n";
533 *file << "\n";
534 return true;
535}
536
537static bool writeDetailedFunction(GeneratedFile* file, Function* function) {
Jean-Luc Brouillet6386ceb2015-04-28 15:06:30 -0700[diff] [blame]538 if (function->hidden()) {
539 return true;
540 }
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]541 const string& name = function->getName();
542
Jean-Luc Brouillet918944e2015-04-30 11:12:40 -0700[diff] [blame]543 *file << "<a name='android_rs:" << name << "'></a>\n";
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]544 *file << "<div class='jd-details'>\n";
545 *file << " <h4 class='jd-details-title'>\n";
546 *file << " <span class='sympad'>" << name << "</span>\n";
547 *file << " <span class='normal'>: " << function->getSummary() << "</span>\n";
548 *file << " </h4>\n";
549
550 *file << " <div class='jd-details-descr'>\n";
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]551 map<string, DetailedFunctionEntry> entries;
552 if (!getUnifiedFunctionPrototypes(function, &entries)) {
553 return false;
554 }
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]555 *file << " <table class='jd-tagtable'><tbody>\n";
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]556 for (auto i : entries) {
557 *file << " <tr>\n";
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]558 *file << " <td>" << i.second.htmlDeclaration << "</td>\n";
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]559 *file << " <td>";
560 writeHtmlVersionTag(file, i.second.info);
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]561 *file << " </td>\n";
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]562 *file << " </tr>\n";
563 }
564 *file << " </tbody></table>\n";
565 *file << " </div>\n";
566
567 if (function->someParametersAreDocumented()) {
568 *file << " <div class='jd-tagdata'>";
569 *file << " <h5 class='jd-tagtitle'>Parameters</h5>\n";
570 *file << " <table class='jd-tagtable'><tbody>\n";
571 for (ParameterEntry* p : function->getParameters()) {
572 *file << " <tr><th>" << p->name << "</th><td>" << p->documentation << "</td></tr>\n";
573 }
574 *file << " </tbody></table>\n";
575 *file << " </div>\n";
576 }
577
578 string ret = function->getReturnDocumentation();
579 if (!ret.empty()) {
580 *file << " <div class='jd-tagdata'>";
581 *file << " <h5 class='jd-tagtitle'>Returns</h5>\n";
582 *file << " <table class='jd-tagtable'><tbody>\n";
583 *file << " <tr><td>" << ret << "</td></tr>\n";
584 *file << " </tbody></table>\n";
585 *file << " </div>\n";
586 }
587
588 *file << " <div class='jd-tagdata jd-tagdescr'>\n";
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]589 writeDeprecatedWarning(file, function);
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]590 if (!generateHtmlParagraphs(file, function->getDescription())) {
591 return false;
592 }
593 *file << " </div>\n";
594
595 *file << "</div>\n";
596 *file << "\n";
597 return true;
598}
599
Jean-Luc Brouillet2217eb72015-04-24 14:41:48 -0700[diff] [blame]600static bool writeDetailedDocumentationFile(const string& directory, const SpecFile& specFile,
601 bool forVerification) {
602 if (!specFile.hasSpecifications()) {
603 // This is true for rs_core.spec
604 return true;
605 }
606
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]607 GeneratedFile file;
Jean-Luc Brouillet2217eb72015-04-24 14:41:48 -0700[diff] [blame]608 const string fileName = stringReplace(specFile.getSpecFileName(), ".spec",
609 forVerification ? ".html" : ".jd");
610 if (!file.start(directory, fileName)) {
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]611 return false;
612 }
613 bool success = true;
614
Jean-Luc Brouillet2217eb72015-04-24 14:41:48 -0700[diff] [blame]615 string title = specFile.getBriefDescription();
616 writeHeader(&file, forVerification, title);
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]617
618 file << "<h2>Overview</h2>\n";
619 if (!generateHtmlParagraphs(&file, specFile.getFullDescription())) {
620 success = false;
621 }
622
623 // Write the summary tables.
624 file << "<h2>Summary</h2>\n";
Jean-Luc Brouillet7c078542015-03-23 16:16:08 -0700[diff] [blame]625 const auto& constants = specFile.getDocumentedConstants();
626 const auto& types = specFile.getDocumentedTypes();
627 const auto& functions = specFile.getDocumentedFunctions();
Jean-Luc Brouillet4a730042015-04-02 16:15:25 -0700[diff] [blame]628
629 writeSummaryTables(&file, constants, types, functions, NON_DEPRECATED_ONLY, false);
630 writeSummaryTables(&file, constants, types, functions, DEPRECATED_ONLY, false);
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]631
632 // Write the full details of each constant, type, and function.
633 if (!constants.empty()) {
634 file << "<h2>Constants</h2>\n";
635 for (auto i : constants) {
636 if (!writeDetailedConstant(&file, i.second)) {
637 success = false;
638 }
639 }
640 }
641 if (!types.empty()) {
642 file << "<h2>Types</h2>\n";
643 for (auto i : types) {
644 if (!writeDetailedType(&file, i.second)) {
645 success = false;
646 }
647 }
648 }
649 if (!functions.empty()) {
650 file << "<h2>Functions</h2>\n";
651 for (auto i : functions) {
652 if (!writeDetailedFunction(&file, i.second)) {
653 success = false;
654 }
655 }
656 }
657
Jean-Luc Brouillet2217eb72015-04-24 14:41:48 -0700[diff] [blame]658 writeFooter(&file, forVerification);
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]659 file.close();
660
661 if (!success) {
662 // If in error, write a final message to make it easier to figure out which file failed.
Jean-Luc Brouillet2217eb72015-04-24 14:41:48 -0700[diff] [blame]663 cerr << fileName << ": Failed due to errors.\n";
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]664 }
665 return success;
666}
667
Jean-Luc Brouillet2217eb72015-04-24 14:41:48 -0700[diff] [blame]668static void generateSnippet(GeneratedFile* file, const string& fileName, const string& title) {
669 const char offset[] = " ";
670 *file << offset << "<li><a href=\"<?cs var:toroot ?>guide/topics/renderscript/reference/"
671 << fileName << "\">\n";
672 *file << offset << " <span class=\"en\">" << title << "</span>\n";
673 *file << offset << "</a></li>\n";
674}
675
676/* Generate a partial file of links that should be cut & pasted into the proper section of the
677 * guide_toc.cs file.
678 */
679static bool generateAndroidTableOfContentSnippet(const string& directory) {
680 GeneratedFile file;
681 if (!file.start(directory, "guide_toc.cs")) {
682 return false;
683 }
684 file << "<!-- Copy and paste the following lines into the RenderScript section of\n";
685 file << " platform/frameworks/base/docs/html/guide/guide_toc.cs\n\n";
686
Jean-Luc Brouillet6386ceb2015-04-28 15:06:30 -0700[diff] [blame]687 const char offset[] = " ";
688 file << offset << "<li class=\"nav-section\">\n";
689 file << offset << " <div class=\"nav-section-header\">\n";
690 file << offset << " <a href=\"<?cs var:toroot ?>guide/topics/renderscript/reference/" <<
691 OVERVIEW_HTML_FILE_NAME << "\">\n";
692 file << offset << " <span class=\"en\">Runtime API Reference</span>\n";
693 file << offset << " </a></div>\n";
694 file << offset << " <ul>\n";
695
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]696 for (auto specFile : systemSpecification.getSpecFiles()) {
Jean-Luc Brouillet2217eb72015-04-24 14:41:48 -0700[diff] [blame]697 if (specFile->hasSpecifications()) {
698 const string fileName = stringReplace(specFile->getSpecFileName(), ".spec", ".html");
699 generateSnippet(&file, fileName, specFile->getBriefDescription());
700 }
701 }
702 generateSnippet(&file, INDEX_HTML_FILE_NAME, "Index");
Jean-Luc Brouillet6386ceb2015-04-28 15:06:30 -0700[diff] [blame]703
704 file << offset << " </ul>\n";
705 file << offset << "</li>\n";
706
Jean-Luc Brouillet2217eb72015-04-24 14:41:48 -0700[diff] [blame]707 return true;
708}
709
710bool generateDocumentation(const string& directory, bool forVerification) {
711 bool success = generateOverview(directory, forVerification) &&
712 generateAlphabeticalIndex(directory, forVerification) &&
713 generateAndroidTableOfContentSnippet(directory);
714 for (auto specFile : systemSpecification.getSpecFiles()) {
715 if (!writeDetailedDocumentationFile(directory, *specFile, forVerification)) {
Jean-Luc Brouilletc5184e22015-03-13 13:51:24 -0700[diff] [blame]716 success = false;
717 }
718 }
719 return success;
720}