Method addJavaDocs

packages/jsii-pacmak/lib/targets/java.ts:2844–2955

(
    doc: spec.Documentable,
    apiLoc: ApiLocation,
    unionHint?: {
      returnsUnion?: spec.TypeReference;
    },
  )

  // eslint-disable-next-line complexity
  private addJavaDocs(
    doc: spec.Documentable,
    apiLoc: ApiLocation,
    unionHint?: {
      returnsUnion?: spec.TypeReference;
    },
  ) {
    const returnsUnion =
      unionHint?.returnsUnion && containsUnionType(unionHint.returnsUnion)
        ? this.renderTypeReference(unionHint.returnsUnion)
        : undefined;

    if (
      !returnsUnion &&
      Object.keys(doc.docs ?? {}).length === 0 &&
      !((doc as spec.Method).parameters ?? []).some(
        (p) => Object.keys(p.docs ?? {}).length !== 0,
      )
    ) {
      return;
    }

    const docs = (doc.docs = doc.docs ?? {});

    const paras = [];

    if (docs.summary) {
      paras.push(stripNewLines(myMarkDownToJavaDoc(renderSummary(docs))));
    }

    if (docs.remarks) {
      paras.push(
        myMarkDownToJavaDoc(
          this.convertSamplesInMarkdown(docs.remarks, apiLoc),
        ).trimRight(),
      );
    }

    if (returnsUnion) {
      paras.push(`Returns union: ${returnsUnion}`);
    }

    if (docs.default) {
      paras.push(`Default: ${docs.default}`); // NOTE: there is no annotation in JavaDoc for this
    }

    if (docs.example) {
      paras.push('Example:');

      const convertedExample = this.convertExample(docs.example, apiLoc);

      // We used to use the slightly nicer `<pre>{@code ...}</pre>`, which doesn't
      // require (and therefore also doesn't allow) escaping special characters.
      //
      // However, code samples may contain block quotes of their own ('*/') that
      // would terminate the block comment from the PoV of the Java tokenizer, and
      // since `{@code ... }` doesn't allow any escaping, there's also no way to encode
      // '*/' in a way that would (a) hide it from the tokenizer and (b) give '*/' back