Package software.amazon.awssdk.codegen.docs

Class DocumentationBuilder

java.lang.Object
software.amazon.awssdk.codegen.docs.DocumentationBuilder
public final class DocumentationBuilder extends Object
Builder for a Javadoc string that orders sections consistently.

  • Constructor Details

    • DocumentationBuilder

      public DocumentationBuilder()

  • Method Details

    • description

      public DocumentationBuilder description(String docs)
      Description of javaodc comment. I.E. what you are reading right now.
      Parameters:
      docs - Description string
      Returns:
      This builder for method chaining.

    • param

      public DocumentationBuilder param(String paramName, String paramDocs)
      Adds a new param to the Javadoc.
      Parameters:
      paramName - Name of parameter.
      paramDocs - Documentation for parameter.
      Returns:
      This builder for method chaining.

    • param

      public DocumentationBuilder param(String paramName, String paramDocs, Object... formatArgs)
      Adds a new param to the Javadoc. Uses String.format(String, Object...) using the given arguments.
      Parameters:
      paramName - Name of parameter.
      paramDocs - Documentation for parameter.
      formatArgs - Arguments referenced by format specifiers.
      Returns:
      This builder for method chaining.

    • returns

      public DocumentationBuilder returns(String returnsDoc)
      Adds documentation for return value. If not set then no return tag will be added to the Javadoc string.
      Parameters:
      returnsDoc - Documentation for return value (if present).
      Returns:
      This builder for method chaining.

    • returns

      public DocumentationBuilder returns(String returnsDoc, Object... formatArgs)
      Adds documentation for return value. If not set then no return tag will be added to the Javadoc string. Uses String.format(String, Object...) using the given arguments.
      Parameters:
      returnsDoc - Documentation for return value (if present).
      formatArgs - Arguments referenced by format specifiers.
      Returns:
      This builder for method chaining.

    • asyncThrows

      public DocumentationBuilder asyncThrows(String exceptionClass, String exceptionDoc)
      Async exceptions are not thrown from the method, rather the returned CompletableFuture is completed exceptionally (CompletableFuture.completeExceptionally(Throwable). Because of this we don't add @throws to the Javadocs or method signature for async methods, we instead add a list of exceptions the future may be completed exceptionally with in the @returns section of the Javadoc.
      Parameters:
      exceptionClass - Class name of thrown exception.
      exceptionDoc - Documentation for thrown exception.
      Returns:
      This builder for method chaining.

    • asyncThrows

      public DocumentationBuilder asyncThrows(Pair<String,String>... exceptions)
      Adds multiple async throws to the Javadoc for each exception name / exception doc pair.
      Parameters:
      exceptions - Multiple pairs of exception name to exception documentation.
      Returns:
      This builder for method chaining.
      See Also:

    • asyncThrows

      public DocumentationBuilder asyncThrows(List<Pair<String,String>> exceptions)
      Adds multiple async throws to the Javadoc for each exception name / exception doc pair.
      Parameters:
      exceptions - Multiple pairs of exception name to exception documentation.
      Returns:
      This builder for method chaining.
      See Also:

    • syncThrows

      public DocumentationBuilder syncThrows(String exceptionClass, String exceptionDoc)
      Adds a throws tag to the Javadoc.
      Parameters:
      exceptionClass - Class name of thrown exception.
      exceptionDoc - Documentation for thrown exception.
      Returns:
      This builder for method chaining.

    • syncThrows

      public DocumentationBuilder syncThrows(Pair<String,String>... exceptions)
      Adds multiple throws tag to the Javadoc for each exception name / exception doc pair.
      Parameters:
      exceptions - Multiple pairs of exception name to exception documentation.
      Returns:
      This builder for method chaining.
      See Also:

    • syncThrows

      public DocumentationBuilder syncThrows(List<Pair<String,String>> exceptions)
      Adds multiple throws tag to the Javadoc for each exception name / exception doc pair.
      Parameters:
      exceptions - Multiple pairs of exception name to exception documentation.
      Returns:
      This builder for method chaining.
      See Also:

    • tag

      public DocumentationBuilder tag(String tagName, String... tagValues)
      Adds an arbitrary tag with values to the Javadoc. This will be added in between the throws and see sections of the Javadoc.
      Parameters:
      tagName - Name of tag to add.
      tagValues - List of values associated with the same.
      Returns:
      This builder for method chaining.

    • see

      public DocumentationBuilder see(String seeLink)
      Adds a @see reference to the Javadocs.
      Parameters:
      seeLink - Reference for @see.
      Returns:
      This builder for method chaining.

    • see

      public DocumentationBuilder see(String seeLink, Object... formatArgs)
      Adds a @see reference to the Javadocs. Uses String.format(String, Object...) using the given arguments.
      Parameters:
      seeLink - Reference for @see.
      formatArgs - Arguments referenced by format specifiers.
      Returns:
      This builder for method chaining.

    • build

      public String build()
      Builds the Javadoc string with the current configuration.
      Returns:
      Formatted Javadoc string.