Escape javadoc special characters (#1342)

<!--- 
Thanks so much for your contribution! If this is your first time
contributing, please ensure that you have read the
[CONTRIBUTING](https://github.com/pulumi/pulumi/blob/master/CONTRIBUTING.md)
documentation.
-->

# Description

<!--- Please include a summary of the change and which issue is fixed.
Please also include relevant motivation and context. -->

Fixes #1271 

Correctly scope comment escapes to outside of code blocks. The resulting
code is both more idiomatic javadoc and safe to embed.

I have two motivating examples:

1. Correctness: Upstream comments that start lines with `@pattern` will
now be escaped to `{@literal @}pattern`. This has prevented us from
publishing in the past
(pulumi/pulumi-gcp#1950,
pulumi/pulumi-auth0#516,
pulumi/pulumi-azure#1979)

2. Idiomaticity: Generated code blocks will no longer be HTML escaped
(since they don't need to be). Instead, they will render correctly.

## Checklist

<!--- Please provide details if the checkbox below is to be left
unchecked. -->
- [X] I have added tests that prove my fix is effective or that my
feature works
<!--- 
User-facing changes require a CHANGELOG entry.
-->
- [ ] I have updated the
[CHANGELOG-PENDING](https://github.com/pulumi/pulumi/blob/master/CHANGELOG_PENDING.md)
file with my change
<!--
If the change(s) in this PR is a modification of an existing call to the
Pulumi Service,
then the service should honor older versions of the CLI where this
change would not exist.
You must then bump the API version in
/pkg/backend/httpstate/client/api.go, as well as add
it to the service.
-->
- [ ] Yes, there are changes in this PR that warrants bumping the Pulumi
Service API version
<!-- @pulumi employees: If yes, you must submit corresponding changes in
the service repo. -->

pkg/codegen/java/gen.go

@@ -414,15 +414,15 @@ func genPropJavadoc(ctx *classFileContext, prop *schema.Property, options propJa
 	}
 
 	if prop.Comment != "" {
-		fprintf(w, "%s\n", formatBlockComment(preamble+prop.Comment, options.indent))
+		fprintf(w, "%s\n", formatForeignBlockCommentFrom(preamble+prop.Comment, len(preamble), options.indent))
 	}
 	if options.isBuilder {
 		fprintf(w, "%s\n", formatBlockComment("@return builder", options.indent))
 	}
 
 	if prop.DeprecationMessage != "" {
 		fprintf(w, "%s * @deprecated\n", options.indent)
-		fprintf(w, "%s\n", formatBlockComment(prop.DeprecationMessage, options.indent))
+		fprintf(w, "%s\n", formatForeignBlockComment(prop.DeprecationMessage, options.indent))
 	}
 	fprintf(w, "%s */\n", options.indent)
 	printObsoleteAttribute(ctx, prop.DeprecationMessage, options.indent)
@@ -523,7 +523,7 @@ func (pt *plainType) genInputType(ctx *classFileContext) error {
 	// Open the class.
 	if pt.comment != "" {
 		fprintf(w, "/**\n")
-		fprintf(w, "%s\n", formatBlockComment(pt.comment, ""))
+		fprintf(w, "%s\n", formatForeignBlockComment(pt.comment, ""))
 		fprintf(w, " */\n")
 	}
 
@@ -931,12 +931,12 @@ func (mod *modContext) genResource(ctx *classFileContext, r *schema.Resource, ar
 	if r.Comment != "" || r.DeprecationMessage != "" {
 		fprintf(w, "/**\n")
 		if r.Comment != "" {
-			fprintf(w, "%s\n", formatBlockComment(r.Comment, ""))
+			fprintf(w, "%s\n", formatForeignBlockComment(r.Comment, ""))
 		}
 
 		if r.DeprecationMessage != "" {
 			fprintf(w, " * @deprecated\n")
-			fprintf(w, "%s\n", formatBlockComment(r.DeprecationMessage, ""))
+			fprintf(w, "%s\n", formatForeignBlockComment(r.DeprecationMessage, ""))
 
 		}
 		fprintf(w, " */\n")
@@ -986,12 +986,12 @@ func (mod *modContext) genResource(ctx *classFileContext, r *schema.Resource, ar
 		if prop.Comment != "" || prop.DeprecationMessage != "" {
 			fprintf(w, "    /**\n")
 			if prop.Comment != "" {
-				fprintf(w, "%s\n", formatBlockComment(prop.Comment, "    "))
+				fprintf(w, "%s\n", formatForeignBlockComment(prop.Comment, "    "))
 			}
 
 			if prop.DeprecationMessage != "" {
 				fprintf(w, "     * @deprecated\n")
-				fprintf(w, "%s\n", formatBlockComment(prop.DeprecationMessage, "    "))
+				fprintf(w, "%s\n", formatForeignBlockComment(prop.DeprecationMessage, "    "))
 
 			}
 			fprintf(w, "     */\n")
@@ -1009,7 +1009,7 @@ func (mod *modContext) genResource(ctx *classFileContext, r *schema.Resource, ar
 
 		if prop.Comment != "" {
 			fprintf(w, "    /**\n")
-			fprintf(w, "%s\n", formatBlockComment("@return "+prop.Comment, "    "))
+			fprintf(w, "%s\n", formatForeignBlockCommentFrom("@return "+prop.Comment, 2, "    "))
 			fprintf(w, "     */\n")
 		}
 
@@ -1220,10 +1220,10 @@ func printCommentFunction(ctx *classFileContext, fun *schema.Function, indent st
 	w := ctx.writer
 	if fun.Comment != "" || fun.DeprecationMessage != "" {
 		fprintf(w, "    /**\n")
-		fprintf(w, "%s\n", formatBlockComment(fun.Comment, indent))
+		fprintf(w, "%s\n", formatForeignBlockComment(fun.Comment, indent))
 		if fun.DeprecationMessage != "" {
 			fprintf(w, "     * @deprecated\n")
-			fprintf(w, "%s\n", formatBlockComment(fun.DeprecationMessage, indent))
+			fprintf(w, "%s\n", formatForeignBlockComment(fun.DeprecationMessage, indent))
 		}
 		fprintf(w, "     */\n")
 	}
@@ -1469,7 +1469,7 @@ func (mod *modContext) genEnum(ctx *classFileContext, enum *schema.EnumType) err
 
 	if enum.Comment != "" {
 		fprintf(w, "%s/**\n", indent)
-		fprintf(w, "%s\n", formatBlockComment(enum.Comment, indent))
+		fprintf(w, "%s\n", formatForeignBlockComment(enum.Comment, indent))
 		fprintf(w, "%s */\n", indent)
 	}
 
@@ -1494,7 +1494,7 @@ func (mod *modContext) genEnum(ctx *classFileContext, enum *schema.EnumType) err
 			if e.Comment != "" || e.DeprecationMessage != "" {
 				fprintf(w, "%s/**\n", indent)
 				if e.Comment != "" {
-					fprintf(w, "%s\n", formatBlockComment(e.Comment, indent))
+					fprintf(w, "%s\n", formatForeignBlockComment(e.Comment, indent))
 				}
 
 				if e.DeprecationMessage != "" {
@@ -1685,7 +1685,7 @@ func (mod *modContext) genConfig(ctx *classFileContext, variables []*schema.Prop
 
 		if p.Comment != "" {
 			fprintf(w, "/**\n")
-			fprintf(w, "%s\n", formatBlockComment(p.Comment, ""))
+			fprintf(w, "%s\n", formatForeignBlockComment(p.Comment, ""))
 			fprintf(w, " */\n")
 		}
 		if err := getterTemplate.Execute(w, getterTemplateContext{