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 Summary

Constructors

Constructor	Description
DocumentationBuilder()

Method Summary

Modifier and Type	Method	Description
DocumentationBuilder	asyncThrows(String exceptionClass, String exceptionDoc)	Async exceptions are not thrown from the method, rather the returned CompletableFuture is completed exceptionally (CompletableFuture.completeExceptionally(Throwable).
DocumentationBuilder	asyncThrows(List<Pair<String,String>> exceptions)	Adds multiple async throws to the Javadoc for each exception name / exception doc pair.
DocumentationBuilder	asyncThrows(Pair<String,String>... exceptions)	Adds multiple async throws to the Javadoc for each exception name / exception doc pair.
String	build()	Builds the Javadoc string with the current configuration.
DocumentationBuilder	description(String docs)	Description of javaodc comment.
DocumentationBuilder	param(String paramName, String paramDocs)	Adds a new param to the Javadoc.
DocumentationBuilder	param(String paramName, String paramDocs, Object... formatArgs)	Adds a new param to the Javadoc.
DocumentationBuilder	returns(String returnsDoc)	Adds documentation for return value.
DocumentationBuilder	returns(String returnsDoc, Object... formatArgs)	Adds documentation for return value.
DocumentationBuilder	see(String seeLink)	Adds a @see reference to the Javadocs.
DocumentationBuilder	see(String seeLink, Object... formatArgs)	Adds a @see reference to the Javadocs.
DocumentationBuilder	syncThrows(String exceptionClass, String exceptionDoc)	Adds a throws tag to the Javadoc.
DocumentationBuilder	syncThrows(List<Pair<String,String>> exceptions)	Adds multiple throws tag to the Javadoc for each exception name / exception doc pair.
DocumentationBuilder	syncThrows(Pair<String,String>... exceptions)	Adds multiple throws tag to the Javadoc for each exception name / exception doc pair.
DocumentationBuilder	tag(String tagName, String... tagValues)	Adds an arbitrary tag with values to the Javadoc.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DocumentationBuilder

public DocumentationBuilder()

Method Detail

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(String, String)

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:

asyncThrows(String, String)

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(String, String)

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:

syncThrows(String, String)

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.