Documentation updates (#1222)

* Swapped manage server and manage channel in Invite#isExpanded docs (#1210)
* Document another possible null return case of Message#getMember (#1204)
* Fix EmbedBuilder constructor javadocs (#1214)
* Update example for jda-nas
* Add more details to modifyMemberRoles docs
* Fix typo

README.md

@@ -574,7 +574,7 @@ Note that this send system creates an extra UDP-Client which causes audio receiv
 since discord identifies the sending UDP-Client as the receiver.
 
 ```java
-JDABuilder builder = new JDABuilder(BOT_TOKEN)
+JDABuilder builder = JDABuilder.createDefault(BOT_TOKEN)
     .setAudioSendFactory(new NativeAudioSendFactory());
 ```
 

src/main/java/net/dv8tion/jda/api/EmbedBuilder.java

@@ -58,7 +58,8 @@ public class EmbedBuilder
     private MessageEmbed.ImageInfo image;
 
     /**
-     * Creates an EmbedBuilder to be used to creates an embed to send.
+     * Constructs a new EmbedBuilder instance, which can be used to create {@link net.dv8tion.jda.api.entities.MessageEmbed MessageEmbeds}.
+     * These can then be sent to a channel using {@link net.dv8tion.jda.api.entities.MessageChannel#sendMessage(MessageEmbed)}.
      * <br>Every part of an embed can be removed or cleared by providing {@code null} to the setter method.
      */
     public EmbedBuilder() { }

src/main/java/net/dv8tion/jda/api/entities/Guild.java

@@ -3488,12 +3488,34 @@ default AuditableRestAction<Void> removeRoleFromMember(@Nonnull String userId, @
      * <br>None of the provided roles may be the <u>Public Role</u> of the current Guild.
      * <br>If a role is both in {@code rolesToAdd} and {@code rolesToRemove} it will be removed.
      *
+     * <h2>Example</h2>
+     * <pre>{@code
+     * public static void promote(Member member) {
+     *     Guild guild = member.getGuild();
+     *     List<Role> pleb = guild.getRolesByName("Pleb", true); // remove all roles named "pleb"
+     *     List<Role> knight = guild.getRolesByName("Knight", true); // add all roles named "knight"
+     *     // update roles in single request
+     *     guild.modifyMemberRoles(member, knight, pleb).queue();
+     * }
+     * }</pre>
+     *
      * <h1>Warning</h1>
      * <b>This may <u>not</u> be used together with any other role add/remove/modify methods for the same Member
      * within one event listener cycle! The changes made by this require cache updates which are triggered by
      * lifecycle events which are received later. This may only be called again once the specific Member has been updated
      * by a {@link net.dv8tion.jda.api.events.guild.member.GenericGuildMemberEvent GenericGuildMemberEvent} targeting the same Member.</b>
      *
+     * <p>This is logically equivalent to:
+     * <pre>{@code
+     * Set<Role> roles = new HashSet<>(member.getRoles());
+     * roles.addAll(rolesToAdd);
+     * roles.removeAll(rolesToRemove);
+     * RestAction<Void> action = guild.modifyMemberRoles(member, roles);
+     * }</pre>
+     *
+     * <p>You can use {@link #addRoleToMember(Member, Role)} and {@link #removeRoleFromMember(Member, Role)} to make updates
+     * independent of the cache.
+     *
      * <p>Possible {@link net.dv8tion.jda.api.requests.ErrorResponse ErrorResponses} caused by
      * the returned {@link net.dv8tion.jda.api.requests.RestAction RestAction} include the following:
      * <ul>
@@ -3504,17 +3526,6 @@ default AuditableRestAction<Void> removeRoleFromMember(@Nonnull String userId, @
      *     <br>The target Member was removed from the Guild before finishing the task</li>
      * </ul>
      *
-     * <h2>Example</h2>
-     * <pre>{@code
-     * public static void promote(Member member) {
-     *     Guild guild = member.getGuild();
-     *     List<Role> pleb = guild.getRolesByName("Pleb", true); // remove all roles named "pleb"
-     *     List<Role> knight = guild.getRolesByName("Knight", true); // add all roles named "knight"
-     *     // update roles in single request
-     *     guild.modifyMemberRoles(member, knight, pleb).queue();
-     * }
-     * }</pre>
-     *
      * @param  member
      *         The {@link net.dv8tion.jda.api.entities.Member Member} that should be modified
      * @param  rolesToAdd

src/main/java/net/dv8tion/jda/api/entities/Invite.java

@@ -296,10 +296,10 @@ default String getUrl()
 
     /**
      * Whether this Invite is expanded or not. Expanded invites contain more information, but they can only be
-     * obtained be {@link net.dv8tion.jda.api.entities.Guild#retrieveInvites() Guild#retrieveInvites()} (requires
-     * {@link net.dv8tion.jda.api.Permission#MANAGE_CHANNEL Permission.MANAGE_CHANNEL}) or
-     * {@link GuildChannel#retrieveInvites() Channel#retrieveInvites()} (requires
-     * {@link net.dv8tion.jda.api.Permission#MANAGE_SERVER Permission.MANAGE_SERVER}).
+     * obtained by {@link net.dv8tion.jda.api.entities.Guild#retrieveInvites() Guild#retrieveInvites()} (requires
+     * {@link net.dv8tion.jda.api.Permission#MANAGE_SERVER Permission.MANAGE_SERVER}) or
+     * {@link net.dv8tion.jda.api.entities.GuildChannel#retrieveInvites() GuildChannel#retrieveInvites()} (requires
+     * {@link net.dv8tion.jda.api.Permission#MANAGE_CHANNEL Permission.MANAGE_CHANNEL}).
      *
      * <p>There is a convenience method {@link #expand()} to get the expanded invite for an unexpanded one.
      *

src/main/java/net/dv8tion/jda/api/entities/Message.java

@@ -407,13 +407,15 @@ public interface Message extends ISnowflake, Formattable
      * Returns the author of this Message as a {@link net.dv8tion.jda.api.entities.Member member}.
      * <br>This is just a shortcut to {@link #getGuild()}{@link net.dv8tion.jda.api.entities.Guild#getMember(User) .getMember(getAuthor())}.
      * <br><b>This is only valid if the Message was actually sent in a TextChannel.</b> This will return {@code null}
-     * if it was not sent from a TextChannel.
+     * if the message was not sent in a TextChannel, or if the message was sent by a Webhook.
      * <br>You can check the type of channel this message was sent from using {@link #isFromType(ChannelType)} or {@link #getChannelType()}.
      *
      * @throws java.lang.UnsupportedOperationException
      *         If this is not a Received Message from {@link net.dv8tion.jda.api.entities.MessageType#DEFAULT MessageType.DEFAULT}
      *
-     * @return Message author, or {@code null} if the message was not sent from a TextChannel.
+     * @return Message author, or {@code null} if the message was not sent in a TextChannel, or if the message was sent by a Webhook.
+     *
+     * @see    #isWebhookMessage()
      */
     @Nullable
     Member getMember();

src/main/java/net/dv8tion/jda/api/requests/RestAction.java

@@ -292,6 +292,12 @@ static Consumer<Object> getDefaultSuccess()
      * <p>When a RestAction times out, it will fail with a {@link java.util.concurrent.TimeoutException TimeoutException}.
      * This is the same as {@code deadline(System.currentTimeMillis() + unit.toMillis(timeout))}.
      *
+     * <h2>Example</h2>
+     * <pre>{@code
+     * action.timeout(10, TimeUnit.SECONDS) // 10 seconds from now
+     *       .queueAfter(20, SECONDS); // request will not be executed within deadline and timeout immediately after 20 seconds
+     * }</pre>
+     *
      * @param  timeout
      *         The timeout to use
      * @param  unit
@@ -321,7 +327,7 @@ default RestAction<T> timeout(long timeout, @Nonnull TimeUnit unit)
      *
      * <h2>Example</h2>
      * <pre>{@code
-     * action.deadline(System.currentTimeMillis() + 100000) // 10 seconds from now
+     * action.deadline(System.currentTimeMillis() + 10000) // 10 seconds from now
      *       .queueAfter(20, SECONDS); // request will not be executed within deadline and timeout immediately after 20 seconds
      * }</pre>
      *