Improve Example documentation. #610
Conversation
hypixel-api-example/src/main/java/net/hypixel/api/example/GetGuildExample.java
Outdated
Show resolved
Hide resolved
| @@ -36,17 +36,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. | |||
There was a problem hiding this comment.
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.
The correct way to say it is, I believe, to drop the comma after "name" and use members' instead of member's
We'll be fetching the guild's stats by its ID for this example, but guilds can
also be looked up using their name or one of their members' Minecraft UUIDs.
There was a problem hiding this comment.
"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).
| * This might print out upto 125 seperate usernames, so you may want to comment the following line out if you're | ||
| * focusing on other info. |
There was a problem hiding this comment.
This 125 members limitation is only an in-game limitation, the endpoint could technically returns more members if there was more players in the guild.
There was a problem hiding this comment.
is this better in reflected with cefffd2?
hypixel-api-example/src/main/java/net/hypixel/api/example/GetGuildExample.java
Show resolved
Hide resolved
| * | ||
| * 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.
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.
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.
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.
125 is a in game limit on how many people can join a guild in hypixel, the endpoint can theoretically return infinite.
hypixel-api-example/src/main/java/net/hypixel/api/example/GetGuildExample.java
Outdated
Show resolved
Hide resolved
firetrqck
changed the title
|
I also added a bit to the README.. |
hypixel-api-example/README.md
Outdated
| - An example of getting player information can be found in [GetPlayerExample](https://github.com/HypixelDev/PublicAPI/blob/master/hypixel-api-example/src/main/java/net/hypixel/api/example/GetPlayerExample.java) | ||
|
|
||
| Information includes their: UUID, network level(exact), rank, mc version, and more! |
There was a problem hiding this comment.
Response data include the player's UUID, network level, rank, client version [<- confirm that], and more!
| * | ||
| * 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.
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.
hypixel-api-example/src/main/java/net/hypixel/api/example/GetGuildExample.java
Show resolved
Hide resolved
| @@ -36,17 +36,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. | |||
There was a problem hiding this comment.
"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).
|
@TheNullicorn as to "members' " vs "members's", I was unaware of the 1st being a convention, and so corrected it and addressed synchronous vs thread blocking in d4f220d, is this language better? |
I felt the urge to make the comments more concise, and in some cases more specific 😅