diff options
author | karl@kubx.ca <karl@kubx.ca> | 2018-04-25 00:39:37 -0400 |
---|---|---|
committer | karl@kubx.ca <karl@kubx.ca> | 2018-05-03 22:40:43 -0400 |
commit | 4bfedb4f2edc4bd71984d79145ab6b0293fe8096 (patch) | |
tree | 09109e6404431210919f40d0fdf3948a664ccfcf | |
parent | 6fee70dd4c82502fefa8259f0d8dbefcece58c60 (diff) |
Improve again javadoc readability and quality
-rw-r--r-- | tensorflow/java/src/gen/cc/op_generator.cc | 7 | ||||
-rw-r--r-- | tensorflow/java/src/gen/cc/op_specs.cc | 57 |
2 files changed, 35 insertions, 29 deletions
diff --git a/tensorflow/java/src/gen/cc/op_generator.cc b/tensorflow/java/src/gen/cc/op_generator.cc index c32ad3b109..00f84bc9cd 100644 --- a/tensorflow/java/src/gen/cc/op_generator.cc +++ b/tensorflow/java/src/gen/cc/op_generator.cc @@ -305,10 +305,11 @@ void RenderInterfaceImpl(const OpSpec& op, RenderMode mode, } } -void RenderOptionsClass(const OpSpec& op, SourceWriter* writer) { +void RenderOptionsClass(const OpSpec& op, const Type& op_class, + SourceWriter* writer) { Type options_class = Type::Class("Options"); Javadoc options_doc = Javadoc::Create( - "Class holding optional attributes of this operation"); + "Optional attributes for {@link " + op_class.full_name() + "}"); writer->BeginInnerType(options_class, PUBLIC | STATIC, &options_doc); for (const AttributeSpec& attribute : op.optional_attributes()) { Method setter = Method::Create(attribute.var().name(), options_class) @@ -410,7 +411,7 @@ void GenerateOp(const OpSpec& op, const EndpointSpec& endpoint, .EndLine() .BeginType(op_class, PUBLIC|FINAL, &dependencies, &op_javadoc); if (!op.optional_attributes().empty()) { - RenderOptionsClass(op, &writer); + RenderOptionsClass(op, op_class, &writer); } RenderFactoryMethod(op, op_class, &writer); RenderGettersAndSetters(op, &writer); diff --git a/tensorflow/java/src/gen/cc/op_specs.cc b/tensorflow/java/src/gen/cc/op_specs.cc index 3645fcf836..a0e7a180f2 100644 --- a/tensorflow/java/src/gen/cc/op_specs.cc +++ b/tensorflow/java/src/gen/cc/op_specs.cc @@ -204,13 +204,21 @@ bool FindAndCut(re2::StringPiece* input, const RE2& expr, } string ParseDocumentation(re2::StringPiece input) { + std::stringstream javadoc_text; + // TODO(karllessard) This is a very minimalist utility method for converting // markdown syntax, as found in ops descriptions, to Javadoc/html tags. Check // for alternatives to increase the level of support for markups. - std::stringstream javadoc_text; + std::vector<string> markups_subexpr; + markups_subexpr.push_back("\n+\\*\\s+"); // lists + markups_subexpr.push_back("\n{2,}"); // paragraphs + markups_subexpr.push_back("`{3,}\\s*[^\\s\n]*\\s*\n"); // code blocks + markups_subexpr.push_back("`+"); // inlined code and code blocks + markups_subexpr.push_back("\\*{1,2}\\b"); // text emphasis + markups_subexpr.push_back("\\["); // hyperlinks + const RE2 markup_expr(str_util::Join(markups_subexpr, "|")); + bool in_list = false; - const RE2 markup_expr( - "\n+\\*[[:blank:]]+|\n{2,}|`{3,}|`{1,2}|\\*{1,2}\\b|\\["); while (true) { re2::StringPiece text; re2::StringPiece markup; @@ -221,52 +229,48 @@ string ParseDocumentation(re2::StringPiece input) { javadoc_text << text; if (markup.starts_with("\n")) { javadoc_text << "\n"; - if (markup.contains("* ")) { - // starts a list item + if (markup.contains("*")) { + // new list item javadoc_text << (in_list ? "</li>\n" : "<ul>\n") << "<li>\n"; in_list = true; - } else if (markup.starts_with("\n\n")) { - if (in_list) { - // ends the current list - javadoc_text << "</li>\n</ul>\n"; - in_list = false; - } else if (!input.starts_with("```")) { - // starts new paragraph (not required if a <pre> block follows) - javadoc_text << "<p>\n"; - } + } else if (in_list) { + // end of list + javadoc_text << "</li>\n</ul>\n"; + in_list = false; + } else if (!input.starts_with("```")) { + // new paragraph (not required if a <pre> block follows) + javadoc_text << "<p>\n"; } - } else if (markup.starts_with("```") && text.empty()) { - // create a multiline code block - re2::StringPiece language; - RE2::Consume(&input, "[\\w\\+]+", &language); - if (FindAndCut(&input, markup.ToString() + "\n*", &text)) { - javadoc_text << "<pre>\n{@code" << text << "}\n</pre>\n"; + } else if (markup.starts_with("```")) { + // code blocks + if (FindAndCut(&input, "```\\s*\n*", &text)) { + javadoc_text << "<pre>{@code\n" << text << "}</pre>\n"; } else { - javadoc_text << markup << language; + javadoc_text << markup; } } else if (markup.starts_with("`")) { - // write inlined code + // inlined code if (FindAndCut(&input, markup, &text)) { javadoc_text << "{@code " << text << "}"; } else { javadoc_text << markup; } } else if (markup == "**") { - // emphase text (strong) + // text emphasis (strong) if (FindAndCut(&input, "\\b\\*{2}", &text)) { javadoc_text << "<b>" << ParseDocumentation(text) << "</b>"; } else { javadoc_text << markup; } } else if (markup == "*") { - // emphase text (light) + // text emphasis (normal) if (FindAndCut(&input, "\\b\\*{1}", &text)) { javadoc_text << "<i>" << ParseDocumentation(text) << "</i>"; } else { javadoc_text << markup; } - } else if (markup == "[") { - // add an external link + } else if (markup.starts_with("[")) { + // hyperlinks string label; string link; if (RE2::Consume(&input, "([^\\[]+)\\]\\((http.+)\\)", &label, &link)) { @@ -277,6 +281,7 @@ string ParseDocumentation(re2::StringPiece input) { javadoc_text << markup; } } else { + // safe fallback javadoc_text << markup; } } |