commit 4a73004df5231d188c41267fee17c566ae7c3631
author Jean-Luc Brouillet <jeanluc@google.com> Thu Apr 02 16:15:25 2015 -0700
committer Jean-Luc Brouillet <jeanluc@google.com> Thu Apr 02 16:16:52 2015 -0700
tree b6a7ec31a3231a9648e7a91db29902c8c215230c
parent 301dc422de63135cd617546dad52e11c89fafaf7

Add "deprecated:" flag to the spec files.

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

Change-Id: I8a606d1af93b0fd0f912ac23aabdb73aa99233b4

api/GenerateHeaderFiles.cpp

diff --git a/api/GenerateHeaderFiles.cpp b/api/GenerateHeaderFiles.cpp
index eb4c9dd..db94b40 100644
--- a/api/GenerateHeaderFiles.cpp
+++ b/api/GenerateHeaderFiles.cpp
@@ -72,7 +72,8 @@
 }
 
 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 @@
         *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 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 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 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 @@
         *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 @@
     // 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);