1*8a52c783SCole Faust**Design:** Convention, **Status:** [Accepted](README.md) 2*8a52c783SCole Faust 3*8a52c783SCole Faust## API Reference 4*8a52c783SCole Faust 5*8a52c783SCole FaustThis page describes a general guideline for API Reference. 6*8a52c783SCole Faust 7*8a52c783SCole Faust### Definition 8*8a52c783SCole Faust- SDK public APIs: all classes/interfaces annotated with `@SdkPublicApi` 9*8a52c783SCole Faust- SDK protected APIs: all classes/interfaces annotated with `@SdkProtectedApi` 10*8a52c783SCole Faust- SDK internal APIs: all classes/interfaces annotated with `@SdkInternalApi` 11*8a52c783SCole Faust 12*8a52c783SCole Faust### General Guideline 13*8a52c783SCole Faust 14*8a52c783SCole Faust- All SDK public APIs MUST have documentation. 15*8a52c783SCole Faust- All public methods in SDK public APIs MUST have documentation except the ones that implement or override a method in an interface or superclass. 16*8a52c783SCole Faust- For SDK protected APIs and internal APIs, documentation is recommended but not required. 17*8a52c783SCole Faust- Javadocs for SDK public APIs in high level libraries such as DynamoDB Enhanced Client SHOULD include code snippets. 18*8a52c783SCole Faust 19*8a52c783SCole Faust### Style guideline 20*8a52c783SCole Faust 21*8a52c783SCole Faust- Javadoc MUST be properly formatted following the [Javadoc standard](https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html). 22*8a52c783SCole Faust- A single `<p>` MUST be used between paragraphs. 23*8a52c783SCole Faust- Use `@link` and `@see` tags to point to related methods/classes. 24*8a52c783SCole Faust- Use `@throws` to specify exceptions that could be thrown from a method. 25*8a52c783SCole Faust- Use `@snippet` to add code snippets. [External code snippets](https://docs.oracle.com/en/java/javase/18/code-snippet/index.html#external-snippets) SHOULD be favored over inline code snippets. 26*8a52c783SCole Faust- Use `@deprecated` tag for deprecated methods. The replacement MUST be documented and linked using `{@link}`. 27*8a52c783SCole Faust- Avoid using `@version` and `@since` tags. 28*8a52c783SCole Faust 29