fix: Add Documentation

[dpcollins-google]

No description provided.

[codecov]

Codecov Report

Merging #221 into master will not change coverage.
The diff coverage is n/a.

@@            Coverage Diff            @@
##             master     #221   +/-   ##
=========================================
  Coverage     72.17%   72.17%           
  Complexity      732      732           
=========================================
  Files           134      134           
  Lines          3936     3936           
  Branches        201      201           
=========================================
  Hits           2841     2841           
  Misses          974      974           
  Partials        121      121           

Impacted Files	Coverage Δ	Complexity Δ
...m/google/cloud/pubsublite/AdminClientSettings.java	0.00% <ø> (ø)	0.00 <0.00> (ø)
.../java/com/google/cloud/pubsublite/CloudRegion.java	100.00% <ø> (ø)	2.00 <0.00> (ø)
...in/java/com/google/cloud/pubsublite/CloudZone.java	60.00% <ø> (ø)	4.00 <0.00> (ø)
...in/java/com/google/cloud/pubsublite/Constants.java	100.00% <ø> (ø)	1.00 <0.00> (ø)
...in/java/com/google/cloud/pubsublite/Endpoints.java	0.00% <ø> (ø)	0.00 <0.00> (ø)
...n/java/com/google/cloud/pubsublite/ErrorCodes.java	100.00% <ø> (ø)	2.00 <0.00> (ø)
...java/com/google/cloud/pubsublite/LocationPath.java	66.66% <ø> (ø)	2.00 <0.00> (ø)
...ava/com/google/cloud/pubsublite/LocationPaths.java	28.57% <ø> (ø)	2.00 <0.00> (ø)
...main/java/com/google/cloud/pubsublite/Message.java	77.77% <ø> (ø)	4.00 <0.00> (ø)
.../main/java/com/google/cloud/pubsublite/Offset.java	100.00% <ø> (ø)	3.00 <0.00> (ø)
... and 24 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update f92f828...64d08e2. Read the comment docs.

[anguillanneuf]

Thank you for documenting! (Worth noting:mvn site failed when I tried to generate javadocs, so I'm reviewing based on my best guess of what will be rendered.)

Most of this looks good. I suggested links in a few places where they will save developers' a Google search.

Unrelated to this PR but would be nice to fix some existing documentation. The code below isn't rendered correctly in the javadocs:

java-pubsublite/google-cloud-pubsublite/src/main/java/com/google/cloud/pubsublite/internal/CloseableMonitor.java

Lines 27 to 44 in 6aa3247

	/**
	* try-with-resources wrapper for enterWhenUninterruptibly. For example:
	*
	* <pre>{@code
	* final Monitor.Guard guard = new Monitor.Guard(monitor.monitor) {
	* @Override
	* public boolean isSatisfied() {
	* assertThat(monitor.monitor.isOccupied()).isTrue();
	* return state;
	* }
	* };
	*
	* try (CloseableMonitor.Hold h = monitor.enterWhenUninterruptibly(guard)) {
	* // Do stuff
	* }
	* // Monitor is automatically released
	* }</pre>
	*/

Remove {@code} and use <pre></pre> only, then replace '<', '>' and '@' with HTML codes <, >, and @ in the code block.

Useful refs:

• <a href="#{@link}">{@link URL}</a>
• {@link package.class#member label}
• "A Guide to Formatting Code Snippets in Javadoc"

[dpcollins-google]

Thank you for documenting! (Worth noting:mvn site failed when I tried to generate javadocs, so I'm reviewing based on my best guess of what will be rendered.)

Most of this looks good. I suggested links in a few places where they will save developers' a Google search.

Unrelated to this PR but would be nice to fix some existing documentation. The code below isn't rendered correctly in the javadocs:

java-pubsublite/google-cloud-pubsublite/src/main/java/com/google/cloud/pubsublite/internal/CloseableMonitor.java

Lines 27 to 44 in 6aa3247

	/**
	* try-with-resources wrapper for enterWhenUninterruptibly. For example:
	*
	* <pre>{@code
	* final Monitor.Guard guard = new Monitor.Guard(monitor.monitor) {
	* @Override
	* public boolean isSatisfied() {
	* assertThat(monitor.monitor.isOccupied()).isTrue();
	* return state;
	* }
	* };
	*
	* try (CloseableMonitor.Hold h = monitor.enterWhenUninterruptibly(guard)) {
	* // Do stuff
	* }
	* // Monitor is automatically released
	* }</pre>
	*/

Remove {@code} and use <pre></pre> only, then replace '<', '>' and '@' with HTML codes <, >, and @ in the code block.

Useful refs:

• <a href="#{@link}">{@link URL}</a>
• {@link package.class#member label}
• "A Guide to Formatting Code Snippets in Javadoc"

I've fixed the assorted issues preventing mvn site from running, it should now run as long as you're in a context that sets JAVA_HOME.

[anguillanneuf]

Awesome! LGTM.