private addJavaDocs()

in packages/jsii-pacmak/lib/targets/java.ts [2718:2818]
87 lines of code
21 McCabe index (conditional complexity)

  private addJavaDocs(
    doc: spec.Documentable,
    apiLoc: ApiLocation,
    defaultText?: string,
  ) {
    if (
      !defaultText &&
      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))));
    } else if (defaultText) {
      paras.push(myMarkDownToJavaDoc(defaultText));
    }

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

    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
      // after processing JavaDocs.
      //
      // Hence, we just resort to HTML-encoding everything (same as we do for code
      // examples that have been translated from MarkDown).
      paras.push(
        myMarkDownToJavaDoc(['```', convertedExample, '```'].join('\n')),
      );
    }

    const tagLines = [];

    if (docs.returns) {
      tagLines.push(`@return ${myMarkDownToJavaDoc(docs.returns)}`);
    }
    if (docs.see) {
      tagLines.push(
        `@see <a href="${escape(docs.see)}">${escape(docs.see)}</a>`,
      );
    }
    if (docs.deprecated) {
      tagLines.push(`@deprecated ${myMarkDownToJavaDoc(docs.deprecated)}`);
    }

    // Params
    if ((doc as spec.Method).parameters) {
      const method = doc as spec.Method;
      if (method.parameters) {
        for (const param of method.parameters) {
          const summary = param.docs?.summary;
          tagLines.push(paramJavadoc(param.name, param.optional, summary));
        }
      }
    }

    if (tagLines.length > 0) {
      paras.push(tagLines.join('\n'));
    }

    const lines = new Array<string>();
    for (const para of paras) {
      if (lines.length > 0) {
        lines.push('<p>');
      }
      lines.push(...para.split('\n').filter((l) => l !== ''));
    }

    this.code.line('/**');
    for (const line of lines) {
      this.code.line(` * ${escapeEndingComment(line)}`);
    }
    this.code.line(' */');
  }