Update APIReference.md (#3467)

Author: zoewangg

docs/design/APIReference.md

@@ -2,7 +2,27 @@
 
 ## API Reference
 
-This page describes a general guideline for API Reference
+This page describes a general guideline for API Reference.
+
+### Definition
+- SDK public APIs: all classes/interfaces annotated with `@SdkPublicApi`
+- SDK protected APIs: all classes/interfaces annotated with `@SdkProtectedApi`
+- SDK internal APIs: all classes/interfaces annotated with `@SdkInternalApi`
+
+### General Guideline
+
+- All SDK public APIs MUST have documentation.
+- All public methods in SDK public APIs MUST have documentation except the ones that implement or override a method in an interface or superclass.
+- For SDK protected APIs and internal APIs, documentation is recommended but not required.
+- Javadocs for SDK public APIs in high level libraries such as DynamoDB Enhanced Client SHOULD include code snippets.
+
+### Style guideline
+
+- Javadoc MUST be properly formatted following the [Javadoc standard](https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html).
+- A single `<p>` MUST be used between paragraphs.
+- Use `@link` and `@see` tags to point to related methods/classes.
+- Use `@throws` to specify exceptions that could be thrown from a method.
+- 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.
+- Use `@deprecated` tag for deprecated methods. The replacement MUST be documented and linked using `{@link}`.
+- Avoid using `@version` and `@since` tags.
 
-- Public APIs MUST have Javadocs, and the documentation MUST be properly formatted following [Javadoc format](https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html)
-- Public Javadocs for high level libraries such as DyanmoDB Enhanced Client or hand-written utilitiy mehods MUST have code snippets as part of Javadocs