Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix: Add Documentation #221

Merged
merged 4 commits into from
Aug 25, 2020
Merged

fix: Add Documentation #221

merged 4 commits into from
Aug 25, 2020

Conversation

dpcollins-google
Copy link
Collaborator

No description provided.

@google-cla google-cla bot added the cla: yes This human has signed the Contributor License Agreement. label Aug 24, 2020
@codecov
Copy link

codecov bot commented Aug 24, 2020

Codecov Report

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

Impacted file tree graph

@@            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.

Copy link
Contributor

@anguillanneuf anguillanneuf left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

/**
* 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 &#60;, &#62;, and &#64; in the code block.

Useful refs:

@product-auto-label product-auto-label bot added the api: pubsublite Issues related to the googleapis/java-pubsublite API. label Aug 25, 2020
@dpcollins-google
Copy link
Collaborator Author

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:

/**
* 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 &#60;, &#62;, and &#64; in the code block.

Useful refs:

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 anguillanneuf self-requested a review August 25, 2020 16:57
Copy link
Contributor

@anguillanneuf anguillanneuf left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Awesome! LGTM.

@dpcollins-google dpcollins-google merged commit 6c430da into master Aug 25, 2020
@dpcollins-google dpcollins-google deleted the documentation branch August 25, 2020 17:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
api: pubsublite Issues related to the googleapis/java-pubsublite API. cla: yes This human has signed the Contributor License Agreement.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants