THRIFT-6108: implemented exception documentation generation

compiler/cpp/src/thrift/generate/t_cpp_generator.cc

@@ -120,6 +120,7 @@ class t_cpp_generator : public t_oop_generator {
   void init_generator() override;
   void close_generator() override;
   std::string display_name() const override;
+  std::string get_doc_type_name(t_type* type) override;
 
   void generate_consts(std::vector<t_const*> consts) override;
 
@@ -455,6 +456,11 @@ class t_cpp_generator : public t_oop_generator {
   friend class ProcessorGenerator;
 };
 
+std::string t_cpp_generator::get_doc_type_name(t_type* type) {
+  type = get_true_type(type);
+  return namespace_prefix(type->get_program()->get_namespace("cpp")) + type->get_name();
+}
+
 /**
  * Prepares for file generation by opening up the necessary file output
  * streams.

compiler/cpp/src/thrift/generate/t_delphi_generator.cc

@@ -359,7 +359,6 @@ class t_delphi_generator : public t_oop_generator {
            " *)\n";
   }
 
-  string xml_encode(string contents);
   string xmldoc_encode(string contents);
   string xmlattrib_encode(string contents);
   void generate_delphi_doc(std::ostream& out, t_field* field);
@@ -469,20 +468,6 @@ class t_delphi_generator : public t_oop_generator {
   std::ostream& indent_impl(std::ostream& os) { return os << indent_impl(); };
 };
 
-// XML encoding
-string t_delphi_generator::xml_encode(string contents) {
-  string str(contents);
-
-  // escape the escape
-  str = replace_all(str, "&", "&amp;");
-
-  // other standard XML entities
-  str = replace_all(str, "<", "&lt;");
-  str = replace_all(str, ">", "&gt;");
-
-  return str;
-}
-
 // XML attribute encoding
 string t_delphi_generator::xmlattrib_encode(string contents) {
   string str(xml_encode(contents));

compiler/cpp/src/thrift/generate/t_haxe_generator.cc

@@ -74,6 +74,7 @@ class t_haxe_generator : public t_oop_generator {
   void init_generator() override;
   void close_generator() override;
   std::string display_name() const override;
+  std::string get_doc_type_name(t_type* type) override;
 
   void generate_consts(std::vector<t_const*> consts) override;
 
@@ -3136,8 +3137,8 @@ void t_haxe_generator::generate_haxe_doc(ostream& out, t_doc* tdoc) {
  * Emits a haxeDoc comment if the provided function object has a doc in Thrift
  */
 void t_haxe_generator::generate_haxe_doc(ostream& out, t_function* tfunction) {
+  stringstream ss;
   if (tfunction->has_doc()) {
-    stringstream ss;
     ss << tfunction->get_doc();
     const vector<t_field*>& fields = tfunction->get_arglist()->get_members();
     vector<t_field*>::const_iterator p_iter;
@@ -3148,8 +3149,18 @@ void t_haxe_generator::generate_haxe_doc(ostream& out, t_function* tfunction) {
         ss << " " << p->get_doc();
       }
     }
-    generate_docstring_comment(out, "/**\n", " * ", ss.str(), " */\n");
   }
+
+  generate_throws_doc(ss, tfunction);
+
+  const std::string result_doc = ss.str();
+  if (!result_doc.empty()) {
+    generate_docstring_comment(out, "/**\n", " * ", result_doc, " */\n");
+  }
+}
+
+std::string t_haxe_generator::get_doc_type_name(t_type* type) {
+  return type_name(type);
 }
 
 std::string t_haxe_generator::generate_isset_check(t_field* field) {

compiler/cpp/src/thrift/generate/t_java_generator.cc

@@ -148,6 +148,7 @@ class t_java_generator : public t_oop_generator {
   void init_generator() override;
   void close_generator() override;
   std::string display_name() const override;
+  std::string get_doc_type_name(t_type* type) override;
 
   void generate_consts(std::vector<t_const*> consts) override;
 
@@ -4692,6 +4693,10 @@ string t_java_generator::type_name(t_type* ttype,
   return make_valid_java_identifier(ttype->get_name());
 }
 
+std::string t_java_generator::get_doc_type_name(t_type* type) {
+  return type_name(type, false, false, false, true);
+}
+
 /**
  * Returns the Java type that corresponds to the thrift type.
  *

compiler/cpp/src/thrift/generate/t_javame_generator.cc

@@ -66,6 +66,7 @@ class t_javame_generator : public t_oop_generator {
   void init_generator() override;
   void close_generator() override;
   std::string display_name() const override;
+  std::string get_doc_type_name(t_type* type) override;
 
   void generate_consts(std::vector<t_const*> consts) override;
 
@@ -188,7 +189,7 @@ class t_javame_generator : public t_oop_generator {
 
   void generate_java_doc(std::ostream& out, t_doc* tdoc) override;
 
-  void generate_java_doc(std::ostream& out, t_function* tdoc) override;
+  void generate_java_doc(std::ostream& out, t_function* tfunction) override;
 
   void generate_java_docstring_comment(std::ostream& out, string contents) override;
 
@@ -2834,6 +2835,17 @@ string t_javame_generator::type_name(t_type* ttype,
   return ttype->get_name();
 }
 
+std::string t_javame_generator::get_doc_type_name(t_type* type) {
+  type = get_true_type(type);
+  const std::string type_name_str = type_name(type);
+  if (type->get_program() != program_) {
+    return type_name_str;
+  }
+
+  const std::string package = type->get_program()->get_namespace("java");
+  return (package.empty() ? "" : package + ".") + type_name_str;
+}
+
 /**
  * Returns the C++ type that corresponds to the thrift type.
  *
@@ -3058,20 +3070,7 @@ void t_javame_generator::generate_java_doc(ostream& out, t_doc* tdoc) {
  * Emits a JavaDoc comment if the provided function object has a doc in Thrift
  */
 void t_javame_generator::generate_java_doc(ostream& out, t_function* tfunction) {
-  if (tfunction->has_doc()) {
-    stringstream ss;
-    ss << tfunction->get_doc();
-    const vector<t_field*>& fields = tfunction->get_arglist()->get_members();
-    vector<t_field*>::const_iterator p_iter;
-    for (p_iter = fields.begin(); p_iter != fields.end(); ++p_iter) {
-      t_field* p = *p_iter;
-      ss << "\n@param " << p->get_name();
-      if (p->has_doc()) {
-        ss << " " << p->get_doc();
-      }
-    }
-    generate_docstring_comment(out, "/**\n", " * ", ss.str(), " */\n");
-  }
+  t_oop_generator::generate_java_doc(out, tfunction);
 }
 
 void t_javame_generator::generate_deep_copy_container(ostream& out,

compiler/cpp/src/thrift/generate/t_kotlin_generator.cc

@@ -77,6 +77,8 @@ class t_kotlin_generator : public t_oop_generator {
   void init_generator() override;
   void close_generator() override;
   std::string display_name() const override;
+  std::string get_doc_type_name(t_type* type) override;
+  void generate_java_doc(std::ostream& out, t_function* function) override;
 
   void generate_consts(std::vector<t_const*> consts) override;
 
@@ -404,6 +406,21 @@ string t_kotlin_generator::type_name(t_type* ttype,
   return kotlin_safe_name(ttype->get_name());
 }
 
+std::string t_kotlin_generator::get_doc_type_name(t_type* type) {
+  return type_name(type, false, false, true);
+}
+
+void t_kotlin_generator::generate_java_doc(ostream& out, t_function* function) {
+  stringstream doc;
+  if (function->has_doc()) {
+    doc << function->get_doc();
+  }
+  generate_throws_doc(doc, function);
+  if (!doc.str().empty()) {
+    generate_docstring_comment(out, "/**\n", " * ", doc.str(), " */\n");
+  }
+}
+
 /**
  * Generates a struct definition for a thrift data type. This will be a org.apache.thrift.TBase
  * implementor.
@@ -1420,7 +1437,7 @@ void t_kotlin_generator::generate_service_interface(t_service* tservice) {
   out << "interface " << tservice->get_name() << " {" << '\n';
   indent_up();
   for (auto tfunc : tservice->get_functions()) {
-    generate_kdoc_comment(out, tfunc);
+    generate_java_doc(out, tfunc);
     indent(out) << function_signature(tfunc) << '\n';
   }
   scope_down(out);

compiler/cpp/src/thrift/generate/t_netstd_generator.cc

@@ -3942,9 +3942,9 @@ void t_netstd_generator::generate_netstd_doc(ostream& out, t_doc* tdoc)
 
 void t_netstd_generator::generate_netstd_doc(ostream& out, t_function* tfunction)
 {
-    if (tfunction->has_doc())
-    {
-        stringstream ps;
+    stringstream ps;
+    if (tfunction->has_doc()) {
+        ps << "<summary>\n" << xml_encode(tfunction->get_doc()) << "</summary>";
         const vector<t_field*>& fields = tfunction->get_arglist()->get_members();
         vector<t_field*>::const_iterator p_iter;
         for (p_iter = fields.begin(); p_iter != fields.end(); ++p_iter)
@@ -3953,18 +3953,38 @@ void t_netstd_generator::generate_netstd_doc(ostream& out, t_function* tfunction
             ps << '\n' << "<param name=\"" << p->get_name() << "\">";
             if (p->has_doc())
             {
-                string str = p->get_doc();
-                str.erase(remove(str.begin(), str.end(), '\n'), str.end());
-                ps << str;
+                ps << xml_encode(p->get_doc());
             }
             ps << "</param>";
         }
+    }
+
+    const vector<t_field*>& exceptions = tfunction->get_xceptions()->get_members();
+    if (!exceptions.empty()) {
+        vector<t_field*>::const_iterator e_iter;
+        for (e_iter = exceptions.begin(); e_iter != exceptions.end(); ++e_iter)
+        {
+            t_field* e = *e_iter;
+            if (!ps.str().empty())
+            {
+                ps << '\n';
+            }
+            ps << "<exception cref=\"" << type_name(e->get_type()) << "\">";
+            if (e->has_doc())
+            {
+                string doc = e->get_doc();
+                while (!doc.empty() && (doc.back() == '\n' || doc.back() == '\r')) {
+                    doc.pop_back();
+                }
+                ps << xml_encode(doc);
+            }
+            ps << "</exception>";
+        }
+    }
 
-        docstring_comment(out,
-                                   "",
-                                   "/// ",
-                                   "<summary>" + string("\n") + tfunction->get_doc() + "</summary>" + ps.str(),
-                                   "");
+    const std::string result_doc = ps.str();
+    if (!result_doc.empty()) {
+        docstring_comment(out, "", "/// ", result_doc, "");
     }
 }
 

compiler/cpp/src/thrift/generate/t_oop_generator.h

@@ -37,6 +37,27 @@ class t_oop_generator : public t_generator {
 public:
   t_oop_generator(t_program* program) : t_generator(program) {}
 
+  virtual std::string get_doc_type_name(t_type* type) {
+    std::string package = type->get_program()->get_namespace("java");
+    return (package.empty() ? "" : package + ".") + type->get_name();
+  }
+
+  void generate_throws_doc(std::stringstream& out, t_function* function) {
+    for (auto* exception : function->get_xceptions()->get_members()) {
+      if (!out.str().empty()) {
+        out << '\n';
+      }
+      out << "@throws " << get_doc_type_name(exception->get_type());
+      if (exception->has_doc()) {
+        std::string doc = exception->get_doc();
+        while (!doc.empty() && (doc.back() == '\n' || doc.back() == '\r')) {
+          doc.pop_back();
+        }
+        out << " " << doc;
+      }
+    }
+  }
+
   /**
    * Scoping, using curly braces!
    */
@@ -92,8 +113,8 @@ class t_oop_generator : public t_generator {
    * Emits a JavaDoc comment if the provided function object has a doc in Thrift
    */
   virtual void generate_java_doc(std::ostream& out, t_function* tfunction) {
+    std::stringstream ss;
     if (tfunction->has_doc()) {
-      std::stringstream ss;
       ss << tfunction->get_doc();
       const std::vector<t_field*>& fields = tfunction->get_arglist()->get_members();
       std::vector<t_field*>::const_iterator p_iter;
@@ -104,7 +125,13 @@ class t_oop_generator : public t_generator {
           ss << " " << p->get_doc();
         }
       }
-      generate_docstring_comment(out, "/**\n", " * ", ss.str(), " */\n");
+    }
+
+    generate_throws_doc(ss, tfunction);
+
+    const std::string result_doc = ss.str();
+    if (!result_doc.empty()) {
+      generate_java_docstring_comment(out, result_doc);
     }
   }
 
@@ -125,6 +152,12 @@ class t_oop_generator : public t_generator {
 
     return str;
   }
+
+  static std::string xml_encode(std::string contents) {
+    contents = replace_all(contents, "&", "&amp;");
+    contents = replace_all(contents, "<", "&lt;");
+    return replace_all(contents, ">", "&gt;");
+  }
 };
 
 #endif