-
Notifications
You must be signed in to change notification settings - Fork 152
Improve Example documentation. #610
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
base: master
Are you sure you want to change the base?
Changes from 3 commits
be8c41d
cefffd2
dd121a9
6213af7
204082d
8cfce40
6359624
e7aac1b
d4f220d
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -21,8 +21,7 @@ public class GetGuildExample { | |
|
||
public static void main(String[] args) { | ||
/* | ||
* Make sure you have a HypixelAPI object set up. You can see how this is done by going to | ||
* the ExampleUtil class. | ||
* Make sure you have a HypixelAPI object set up. You can see how this is done in the ExampleUtil class. | ||
* | ||
* See the finally{} block below for how to shutdown this API once you're all done. | ||
*/ | ||
|
@@ -36,17 +35,17 @@ public static void main(String[] args) { | |
try { | ||
/* | ||
* We'll be fetching the guild's stats using its ID for this example, but guilds can | ||
* also be looked up using their name, or one of their members' Minecraft UUIDs. | ||
* also be looked up by their name, or one of their member's Minecraft UUIDs. | ||
* - HypixelAPI.getGuildByName(String) | ||
* - HypixelAPI.getGuildByPlayer(UUID) | ||
*/ | ||
String guildId = ExampleUtil.GUILD_ID; | ||
|
||
/* | ||
* Here, we store the response from the API in our variable. | ||
* Here, we store the response from the API. | ||
* | ||
* We call `.get()` at the end so that we can use the reply in the same thread. | ||
* The downside is that the current thread freezes (or "blocks") until the API responds. | ||
* The downside is that this is synchronous operation. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Original message should be kept as we are here losing the fact that the performances are dependant of the API response time. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The current thread being blocked until something happening (in this case the API responding) is the definition of synchronous operation(which dependent the time the API takes to respond is how long the thread takes to be unblocked hence the performance being dependent on api response time) There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The Hypixel API is very accessible, so it often attracts a lot of new developers, which I catered these examples toward. From a newbie's perspective, I worry that "synchronous" might send them down a rabbit hole that makes their learning curve feel a lot steeper. Words like "blocks" and "thread" are there so that those who understand those concepts get the gist. |
||
* If this is a problem for you, instead use: | ||
* | ||
* .whenComplete((apiReply, error) -> { | ||
|
@@ -61,7 +60,7 @@ public static void main(String[] args) { | |
System.err.println("Oh no, our API request failed!"); | ||
|
||
/* | ||
* If an ExecutionException is thrown, it's typically because of an API error. | ||
* If an ExecutionException is an arbitary error, typically because of an API error. | ||
firetrqck marked this conversation as resolved.
Show resolved
Hide resolved
|
||
* Use `getCause()` to determine what the actual problem is. | ||
*/ | ||
e.getCause().printStackTrace(); | ||
|
@@ -127,8 +126,9 @@ public static void main(String[] args) { | |
/* | ||
* Finally, we'll print some information about each member in the guild. | ||
* | ||
* This might print out A LOT, so you may want to comment the following line out if you're | ||
* focusing on some of the guild's other info. | ||
* This might print out a lot usernames(in theory infinity, | ||
* practically upto 125, the *current* in game member limit), | ||
* so you may want to comment the following line out if you're focusing on other info. | ||
firetrqck marked this conversation as resolved.
Show resolved
Hide resolved
|
||
*/ | ||
printGuildMembers(guild.getMembers()); | ||
} | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Original message is correct.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
They have the same meaning but the edit is more grammatically correct and imo roles off the tongue easier.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The correct way to say it is, I believe, to drop the comma after "name" and use
members'
instead ofmember's
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"members" should definitely be plural, since the alternative would be "one of their member". As for "members'" vs "members's", I think it's just a matter of style, but the former is normally preferred (Firefox's spellcheck highlights the latter, if that counts for anything).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
fixed