From b2f3bcdd08811e0a138d0debf51f31b34bf6a443 Mon Sep 17 00:00:00 2001 From: Bryan Duxbury Date: Wed, 2 May 2012 21:39:01 +0000 Subject: [PATCH] THRIFT-681. The HTML generator does not handle JavaDoc style comments very well Patch: Kevin Burnett git-svn-id: https://svn.apache.org/repos/asf/thrift/trunk@1333222 13f79535-47bb-0310-9956-ffa450edef68 --- compiler/cpp/src/generate/t_html_generator.cc | 147 ++++++++++++------ compiler/cpp/src/generate/t_java_generator.cc | 14 +- 2 files changed, 104 insertions(+), 57 deletions(-) diff --git a/compiler/cpp/src/generate/t_html_generator.cc b/compiler/cpp/src/generate/t_html_generator.cc index 77cb972d..6372ab4a 100644 --- a/compiler/cpp/src/generate/t_html_generator.cc +++ b/compiler/cpp/src/generate/t_html_generator.cc @@ -27,6 +27,7 @@ #include #include #include "t_generator.h" +#include "t_html_generator.h" #include "platform.h" using namespace std; @@ -77,6 +78,7 @@ class t_html_generator : public t_generator { void print_doc (t_doc* tdoc); int print_type (t_type* ttype); void print_const_value(t_const_value* tvalue); + void print_fn_args_doc(t_function* tfunction); std::ofstream f_out_; }; @@ -85,8 +87,8 @@ class t_html_generator : public t_generator { * Emits the Table of Contents links at the top of the module's page */ void t_html_generator::generate_program_toc() { - f_out_ << "" - << "" << endl; + f_out_ << "
ModuleServicesData typesConstants
" + << "" << endl; generate_program_toc_row(program_); f_out_ << "
ModuleServicesData typesConstants
" << endl; } @@ -186,15 +188,15 @@ void t_html_generator::generate_program_toc_row(t_program* tprog) { dt_iter != data_types.end(); dt_iter++) { f_out_ << dt_iter->second << "
" << endl; } - f_out_ << "" << endl << ""; + f_out_ << "" << endl << ""; if (!tprog->get_consts().empty()) { map const_html; vector consts = tprog->get_consts(); vector::iterator con_iter; for (con_iter = consts.begin(); con_iter != consts.end(); ++con_iter) { string name = (*con_iter)->get_name(); - string html ="" + name + ""; + string html ="" + name + ""; const_html.insert(pair(name, html)); } for (map::iterator con_iter = const_html.begin(); @@ -219,10 +221,11 @@ void t_html_generator::generate_program() { f_out_ << "" << endl; f_out_ << "" << endl; f_out_ << "" << endl; - f_out_ << "" - << endl; + f_out_ << "" << endl; f_out_ << "Thrift module: " << program_->get_name() - << "" << endl << "

Thrift module: " + << "" << endl + << "
" << endl + << "

Thrift module: " << program_->get_name() << "

" << endl; print_doc(program_); @@ -232,8 +235,8 @@ void t_html_generator::generate_program() { if (!program_->get_consts().empty()) { f_out_ << "

Constants

" << endl; vector consts = program_->get_consts(); - f_out_ << ""; - f_out_ << "" << endl; + f_out_ << "
ConstantTypeValue
"; + f_out_ << "" << endl; generate_consts(consts); f_out_ << "
ConstantTypeValue
"; } @@ -283,7 +286,7 @@ void t_html_generator::generate_program() { } } - f_out_ << "" << endl; + f_out_ << "
" << endl; f_out_.close(); generate_index(); @@ -300,37 +303,29 @@ void t_html_generator::generate_index() { f_out_ << "" << endl; f_out_ << "All Thrift declarations" + << endl << "
" << endl << "

All Thrift declarations

" << endl; - f_out_ << "" - << "" << endl; + f_out_ << "
ModuleServicesData typesConstants
" + << "" << endl; vector programs; generate_program_toc_rows(program_, programs); f_out_ << "
ModuleServicesData typesConstants
" << endl; - f_out_ << "" << endl; + f_out_ << "
" << endl; f_out_.close(); } void t_html_generator::generate_css() { string css_fname = get_out_dir() + "style.css"; f_out_.open(css_fname.c_str()); + f_out_ << BOOTSTRAP_CSS() << endl; f_out_ << "/* Auto-generated CSS for generated Thrift docs */" << endl; - f_out_ << - "body { font-family: Tahoma, sans-serif; }" << endl; - f_out_ << - "pre { background-color: #dddddd; padding: 6px; }" << endl; - f_out_ << - "h3,h4 { padding-top: 0px; margin-top: 0px; }" << endl; - f_out_ << - "div.definition { border: 1px solid gray; margin: 10px; padding: 10px; }" << endl; - f_out_ << - "div.extends { margin: -0.5em 0 1em 5em }" << endl; - f_out_ << - "table { border: 1px solid grey; border-collapse: collapse; }" << endl; - f_out_ << - "td { border: 1px solid grey; padding: 1px 6px; vertical-align: top; }" << endl; - f_out_ << - "th { border: 1px solid black; background-color: #bbbbbb;" << endl << - " text-align: left; padding: 1px 6px; }" << endl; + f_out_ << "h3, h4 { margin-bottom: 6px; }" << endl; + f_out_ << "div.definition { border: 1px solid #CCC; margin-bottom: 10px; padding: 10px; }" << endl; + f_out_ << "div.extends { margin: -0.5em 0 1em 5em }" << endl; + f_out_ << "td { vertical-align: top; }" << endl; + f_out_ << "table { empty-cells: show; }" << endl; + f_out_ << "code { line-height: 20px; }" << endl; + f_out_ << ".table-bordered th, .table-bordered td { border-bottom: 1px solid #DDDDDD; }" << endl; f_out_.close(); } @@ -461,6 +456,59 @@ void t_html_generator::print_const_value(t_const_value* tvalue) { } } +/** + * Prints out documentation for arguments/exceptions of a function, if any documentation has been supplied. + */ +void t_html_generator::print_fn_args_doc(t_function* tfunction) { + bool has_docs = false; + vector args = tfunction->get_arglist()->get_members(); + vector::iterator arg_iter = args.begin(); + if (arg_iter != args.end()) { + for ( ; arg_iter != args.end(); arg_iter++) { + if ((*arg_iter)->has_doc() && !(*arg_iter)->get_doc().empty()) + has_docs = true; + } + if (has_docs) { + arg_iter = args.begin(); + f_out_ << "

get_name() + << "\">Parameters

" << endl; + f_out_ << ""; + f_out_ << ""; + for ( ; arg_iter != args.end(); arg_iter++) { + f_out_ << "" << endl; + } + f_out_ << "
NameDescription
" << (*arg_iter)->get_name(); + f_out_ << ""; + f_out_ << (*arg_iter)->get_doc(); + f_out_ << "
"; + } + } + + has_docs = false; + vector excepts = tfunction->get_xceptions()->get_members(); + vector::iterator ex_iter = excepts.begin(); + if (ex_iter != excepts.end()) { + for ( ; ex_iter != excepts.end(); ex_iter++) { + if ((*ex_iter)->has_doc() && !(*ex_iter)->get_doc().empty()) + has_docs = true; + } + if (has_docs) { + ex_iter = excepts.begin(); + f_out_ << "

get_name() + << "\">Exceptions

" << endl; + f_out_ << ""; + f_out_ << ""; + for ( ; ex_iter != excepts.end(); ex_iter++) { + f_out_ << "" << endl; + } + f_out_ << "
TypeDescription
" << (*ex_iter)->get_type()->get_name(); + f_out_ << ""; + f_out_ << (*ex_iter)->get_doc(); + f_out_ << "
"; + } + } +} + /** * Generates a typedef. * @@ -491,7 +539,7 @@ void t_html_generator::generate_enum(t_enum* tenum) { print_doc(tenum); vector values = tenum->get_constants(); vector::iterator val_iter; - f_out_ << "
" << endl; + f_out_ << "
" << endl; for (val_iter = values.begin(); val_iter != values.end(); ++val_iter) { f_out_ << ""; if (tconst->has_doc()) { @@ -537,8 +585,8 @@ void t_html_generator::generate_struct(t_struct* tstruct) { f_out_ << name << "" << endl; vector members = tstruct->get_members(); vector::iterator mem_iter = members.begin(); - f_out_ << "
"; f_out_ << (*val_iter)->get_name(); @@ -508,9 +556,9 @@ void t_html_generator::generate_enum(t_enum* tenum) { void t_html_generator::generate_const(t_const* tconst) { string name = tconst->get_name(); f_out_ << "
" << name - << ""; + << ""; print_type(tconst->get_type()); - f_out_ << ""; + f_out_ << ""; print_const_value(tconst->get_value()); f_out_ << "
"; - f_out_ << "" + f_out_ << "
KeyFieldTypeDescriptionRequirednessDefault value
"; + f_out_ << "" << endl; for ( ; mem_iter != members.end(); mem_iter++) { f_out_ << "
KeyFieldTypeDescriptionRequirednessDefault value
" << (*mem_iter)->get_key() << ""; @@ -606,22 +654,20 @@ void t_html_generator::generate_service(t_service* tservice) { offset += fn_name.size() + 2; vector args = (*fn_iter)->get_arglist()->get_members(); vector::iterator arg_iter = args.begin(); - if (arg_iter != args.end()) { - for ( ; arg_iter != args.end(); arg_iter++) { - if (!first) { - f_out_ << "," << endl; - for (int i = 0; i < offset; ++i) { - f_out_ << " "; - } - } - first = false; - print_type((*arg_iter)->get_type()); - f_out_ << " " << (*arg_iter)->get_name(); - if ((*arg_iter)->get_value() != NULL) { - f_out_ << " = "; - print_const_value((*arg_iter)->get_value()); + for ( ; arg_iter != args.end(); arg_iter++) { + if (!first) { + f_out_ << "," << endl; + for (int i = 0; i < offset; ++i) { + f_out_ << " "; } } + first = false; + print_type((*arg_iter)->get_type()); + f_out_ << " " << (*arg_iter)->get_name(); + if ((*arg_iter)->get_value() != NULL) { + f_out_ << " = "; + print_const_value((*arg_iter)->get_value()); + } } f_out_ << ")" << endl; first = true; @@ -640,6 +686,7 @@ void t_html_generator::generate_service(t_service* tservice) { } f_out_ << ""; print_doc(*fn_iter); + print_fn_args_doc(*fn_iter); f_out_ << ""; } } diff --git a/compiler/cpp/src/generate/t_java_generator.cc b/compiler/cpp/src/generate/t_java_generator.cc index 945d6ef0..ca061f79 100755 --- a/compiler/cpp/src/generate/t_java_generator.cc +++ b/compiler/cpp/src/generate/t_java_generator.cc @@ -154,9 +154,9 @@ public: void generate_union_hashcode(ofstream& out, t_struct* tstruct); void generate_scheme_map(ofstream& out, t_struct* tstruct); - void generate_standard_writer(ofstream& out, t_struct* tstruct); + void generate_standard_writer(ofstream& out, t_struct* tstruct, bool is_result); void generate_standard_reader(ofstream& out, t_struct* tstruct); - void generate_java_struct_standard_scheme(ofstream& out, t_struct* tstruct); + void generate_java_struct_standard_scheme(ofstream& out, t_struct* tstruct, bool is_result); void generate_java_struct_tuple_scheme(ofstream& out, t_struct* tstruct); void generate_java_struct_tuple_reader(ofstream& out, t_struct* tstruct); @@ -1451,7 +1451,7 @@ void t_java_generator::generate_java_struct_definition(ofstream &out, generate_java_struct_write_object(out, tstruct); generate_java_struct_read_object(out, tstruct); - generate_java_struct_standard_scheme(out, tstruct); + generate_java_struct_standard_scheme(out, tstruct, is_result); generate_java_struct_tuple_scheme(out, tstruct); scope_down(out); @@ -4005,7 +4005,7 @@ void t_java_generator::generate_standard_reader(ofstream& out, t_struct* tstruct out << indent() << "}" << endl; } -void t_java_generator::generate_standard_writer(ofstream& out, t_struct* tstruct) { +void t_java_generator::generate_standard_writer(ofstream& out, t_struct* tstruct, bool is_result) { indent_up(); out << indent() << "public void write(org.apache.thrift.protocol.TProtocol oprot, " << @@ -4026,7 +4026,7 @@ void t_java_generator::generate_standard_writer(ofstream& out, t_struct* tstruct indent() << "if (struct." << (*f_iter)->get_name() << " != null) {" << endl; indent_up(); } - bool optional = (*f_iter)->get_req() == t_field::T_OPTIONAL; + bool optional = ((*f_iter)->get_req() == t_field::T_OPTIONAL) || (is_result && !null_allowed); if (optional) { indent(out) << "if (" << "struct." << generate_isset_check((*f_iter)) << ") {" << endl; indent_up(); @@ -4059,7 +4059,7 @@ void t_java_generator::generate_standard_writer(ofstream& out, t_struct* tstruct indent_down(); } -void t_java_generator::generate_java_struct_standard_scheme(ofstream& out, t_struct* tstruct){ +void t_java_generator::generate_java_struct_standard_scheme(ofstream& out, t_struct* tstruct, bool is_result){ indent(out) << "private static class " << tstruct->get_name() << "StandardSchemeFactory implements SchemeFactory {" << endl; indent_up(); indent(out) << "public " << tstruct->get_name() << "StandardScheme getScheme() {" << endl; @@ -4075,7 +4075,7 @@ void t_java_generator::generate_java_struct_standard_scheme(ofstream& out, t_str generate_standard_reader(out, tstruct); indent_down(); out << endl; - generate_standard_writer(out, tstruct); + generate_standard_writer(out, tstruct, is_result); out << indent() << "}" << endl << -- 2.17.1