SteamWar/Paper
9
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Pulling all pending Bukkit-JavaDoc changes

Browse Source 
A special thanks goes to @aerouk for almost all of the changes found here.

By: Wesley Wolfe <weswolf@aol.com>
This commit is contained in:
Bukkit/Spigot
2013-12-15 01:07:43 -05:00
parent 800679913f
commit bb50f1a774
310 changed files with 4218 additions and 2904 deletions
Download Patch File Download Diff File Expand all files Collapse all files

78
paper-api/src/main/java/org/bukkit/configuration/file/FileConfiguration.java
View File

@@ -16,7 +16,8 @@ import org.bukkit.configuration.Configuration;
import org.bukkit.configuration.MemoryConfiguration;
/**
* This is a base class for all File based implementations of {@link Configuration}
* This is a base class for all File based implementations of {@link
* Configuration}
*/
public abstract class FileConfiguration extends MemoryConfiguration {
/**
@@ -27,8 +28,8 @@ public abstract class FileConfiguration extends MemoryConfiguration {
}
/**
* Creates an empty {@link FileConfiguration} using the specified {@link Configuration}
* as a source for all default values.
* Creates an empty {@link FileConfiguration} using the specified {@link
* Configuration} as a source for all default values.
*
* @param defaults Default value provider
*/
@@ -39,11 +40,13 @@ public abstract class FileConfiguration extends MemoryConfiguration {
/**
* Saves this {@link FileConfiguration} to the specified location.
* <p>
* If the file does not exist, it will be created. If already exists, it will
* be overwritten. If it cannot be overwritten or created, an exception will be thrown.
* If the file does not exist, it will be created. If already exists, it
* will be overwritten. If it cannot be overwritten or created, an
* exception will be thrown.
*
* @param file File to save to.
* @throws IOException Thrown when the given file cannot be written to for any reason.
* @throws IOException Thrown when the given file cannot be written to for
* any reason.
* @throws IllegalArgumentException Thrown when file is null.
*/
public void save(File file) throws IOException {
@@ -65,11 +68,13 @@ public abstract class FileConfiguration extends MemoryConfiguration {
/**
* Saves this {@link FileConfiguration} to the specified location.
* <p>
* If the file does not exist, it will be created. If already exists, it will
* be overwritten. If it cannot be overwritten or created, an exception will be thrown.
* If the file does not exist, it will be created. If already exists, it
* will be overwritten. If it cannot be overwritten or created, an
* exception will be thrown.
*
* @param file File to save to.
* @throws IOException Thrown when the given file cannot be written to for any reason.
* @throws IOException Thrown when the given file cannot be written to for
* any reason.
* @throws IllegalArgumentException Thrown when file is null.
*/
public void save(String file) throws IOException {
@@ -88,15 +93,19 @@ public abstract class FileConfiguration extends MemoryConfiguration {
/**
* Loads this {@link FileConfiguration} from the specified location.
* <p>
* All the values contained within this configuration will be removed, leaving
* only settings and defaults, and the new values will be loaded from the given file.
* All the values contained within this configuration will be removed,
* leaving only settings and defaults, and the new values will be loaded
* from the given file.
* <p>
* If the file cannot be loaded for any reason, an exception will be thrown.
* If the file cannot be loaded for any reason, an exception will be
* thrown.
*
* @param file File to load from.
* @throws FileNotFoundException Thrown when the given file cannot be opened.
* @throws FileNotFoundException Thrown when the given file cannot be
* opened.
* @throws IOException Thrown when the given file cannot be read.
* @throws InvalidConfigurationException Thrown when the given file is not a valid Configuration.
* @throws InvalidConfigurationException Thrown when the given file is not
* a valid Configuration.
* @throws IllegalArgumentException Thrown when file is null.
*/
public void load(File file) throws FileNotFoundException, IOException, InvalidConfigurationException {
@@ -108,12 +117,14 @@ public abstract class FileConfiguration extends MemoryConfiguration {
/**
* Loads this {@link FileConfiguration} from the specified stream.
* <p>
* All the values contained within this configuration will be removed, leaving
* only settings and defaults, and the new values will be loaded from the given stream.
* All the values contained within this configuration will be removed,
* leaving only settings and defaults, and the new values will be loaded
* from the given stream.
*
* @param stream Stream to load from
* @throws IOException Thrown when the given file cannot be read.
* @throws InvalidConfigurationException Thrown when the given file is not a valid Configuration.
* @throws InvalidConfigurationException Thrown when the given file is not
* a valid Configuration.
* @throws IllegalArgumentException Thrown when stream is null.
*/
public void load(InputStream stream) throws IOException, InvalidConfigurationException {
@@ -141,15 +152,19 @@ public abstract class FileConfiguration extends MemoryConfiguration {
/**
* Loads this {@link FileConfiguration} from the specified location.
* <p>
* All the values contained within this configuration will be removed, leaving
* only settings and defaults, and the new values will be loaded from the given file.
* All the values contained within this configuration will be removed,
* leaving only settings and defaults, and the new values will be loaded
* from the given file.
* <p>
* If the file cannot be loaded for any reason, an exception will be thrown.
* If the file cannot be loaded for any reason, an exception will be
* thrown.
*
* @param file File to load from.
* @throws FileNotFoundException Thrown when the given file cannot be opened.
* @throws FileNotFoundException Thrown when the given file cannot be
* opened.
* @throws IOException Thrown when the given file cannot be read.
* @throws InvalidConfigurationException Thrown when the given file is not a valid Configuration.
* @throws InvalidConfigurationException Thrown when the given file is not
* a valid Configuration.
* @throws IllegalArgumentException Thrown when file is null.
*/
public void load(String file) throws FileNotFoundException, IOException, InvalidConfigurationException {
@@ -159,24 +174,29 @@ public abstract class FileConfiguration extends MemoryConfiguration {
}
/**
* Loads this {@link FileConfiguration} from the specified string, as opposed to from file.
* Loads this {@link FileConfiguration} from the specified string, as
* opposed to from file.
* <p>
* All the values contained within this configuration will be removed, leaving
* only settings and defaults, and the new values will be loaded from the given string.
* All the values contained within this configuration will be removed,
* leaving only settings and defaults, and the new values will be loaded
* from the given string.
* <p>
* If the string is invalid in any way, an exception will be thrown.
*
* @param contents Contents of a Configuration to load.
* @throws InvalidConfigurationException Thrown if the specified string is invalid.
* @throws InvalidConfigurationException Thrown if the specified string is
* invalid.
* @throws IllegalArgumentException Thrown if contents is null.
*/
public abstract void loadFromString(String contents) throws InvalidConfigurationException;
/**
* Compiles the header for this {@link FileConfiguration} and returns the result.
* Compiles the header for this {@link FileConfiguration} and returns the
* result.
* <p>
* This will use the header from {@link #options()} -> {@link FileConfigurationOptions#header()},
* respecting the rules of {@link FileConfigurationOptions#copyHeader()} if set.
* This will use the header from {@link #options()} -> {@link
* FileConfigurationOptions#header()}, respecting the rules of {@link
* FileConfigurationOptions#copyHeader()} if set.
*
* @return Compiled header
*/

54
paper-api/src/main/java/org/bukkit/configuration/file/FileConfigurationOptions.java
View File

@@ -3,7 +3,8 @@ package org.bukkit.configuration.file;
import org.bukkit.configuration.*;
/**
* Various settings for controlling the input and output of a {@link FileConfiguration}
* Various settings for controlling the input and output of a {@link
* FileConfiguration}
*/
public class FileConfigurationOptions extends MemoryConfigurationOptions {
private String header = null;
@@ -33,13 +34,14 @@ public class FileConfigurationOptions extends MemoryConfigurationOptions {
/**
* Gets the header that will be applied to the top of the saved output.
* <p>
* This header will be commented out and applied directly at the top of the
* generated output of the {@link FileConfiguration}. It is not required to
* include a newline at the end of the header as it will automatically be applied,
* but you may include one if you wish for extra spacing.
* This header will be commented out and applied directly at the top of
* the generated output of the {@link FileConfiguration}. It is not
* required to include a newline at the end of the header as it will
* automatically be applied, but you may include one if you wish for extra
* spacing.
* <p>
* Null is a valid value which will indicate that no header is to be applied.
* The default value is null.
* Null is a valid value which will indicate that no header is to be
* applied. The default value is null.
*
* @return Header
*/
@@ -50,12 +52,14 @@ public class FileConfigurationOptions extends MemoryConfigurationOptions {
/**
* Sets the header that will be applied to the top of the saved output.
* <p>
* This header will be commented out and applied directly at the top of the
* generated output of the {@link FileConfiguration}. It is not required to
* include a newline at the end of the header as it will automatically be applied,
* but you may include one if you wish for extra spacing.
* This header will be commented out and applied directly at the top of
* the generated output of the {@link FileConfiguration}. It is not
* required to include a newline at the end of the header as it will
* automatically be applied, but you may include one if you wish for extra
* spacing.
* <p>
* Null is a valid value which will indicate that no header is to be applied.
* Null is a valid value which will indicate that no header is to be
* applied.
*
* @param value New header
* @return This object, for chaining
@@ -69,12 +73,15 @@ public class FileConfigurationOptions extends MemoryConfigurationOptions {
* Gets whether or not the header should be copied from a default source.
* <p>
* If this is true, if a default {@link FileConfiguration} is passed to
* {@link FileConfiguration#setDefaults(org.bukkit.configuration.Configuration)}
* then upon saving it will use the header from that config, instead of the one provided here.
* {@link
* FileConfiguration#setDefaults(org.bukkit.configuration.Configuration)}
* then upon saving it will use the header from that config, instead of
* the one provided here.
* <p>
* If no default is set on the configuration, or the default is not of type FileConfiguration,
* or that config has no header ({@link #header()} returns null) then the header
* specified in this configuration will be used.
* If no default is set on the configuration, or the default is not of
* type FileConfiguration, or that config has no header ({@link #header()}
* returns null) then the header specified in this configuration will be
* used.
* <p>
* Defaults to true.
*
@@ -88,12 +95,15 @@ public class FileConfigurationOptions extends MemoryConfigurationOptions {
* Sets whether or not the header should be copied from a default source.
* <p>
* If this is true, if a default {@link FileConfiguration} is passed to
* {@link FileConfiguration#setDefaults(org.bukkit.configuration.Configuration)}
* then upon saving it will use the header from that config, instead of the one provided here.
* {@link
* FileConfiguration#setDefaults(org.bukkit.configuration.Configuration)}
* then upon saving it will use the header from that config, instead of
* the one provided here.
* <p>
* If no default is set on the configuration, or the default is not of type FileConfiguration,
* or that config has no header ({@link #header()} returns null) then the header
* specified in this configuration will be used.
* If no default is set on the configuration, or the default is not of
* type FileConfiguration, or that config has no header ({@link #header()}
* returns null) then the header specified in this configuration will be
* used.
* <p>
* Defaults to true.
*

6
paper-api/src/main/java/org/bukkit/configuration/file/YamlConfiguration.java
View File

@@ -160,7 +160,8 @@ public class YamlConfiguration extends FileConfiguration {
* Creates a new {@link YamlConfiguration}, loading from the given file.
* <p>
* Any errors loading the Configuration will be logged and then ignored.
* If the specified input is not a valid config, a blank config will be returned.
* If the specified input is not a valid config, a blank config will be
* returned.
*
* @param file Input file
* @return Resulting configuration
@@ -187,7 +188,8 @@ public class YamlConfiguration extends FileConfiguration {
* Creates a new {@link YamlConfiguration}, loading from the given stream.
* <p>
* Any errors loading the Configuration will be logged and then ignored.
* If the specified input is not a valid config, a blank config will be returned.
* If the specified input is not a valid config, a blank config will be
* returned.
*
* @param stream Input stream
* @return Resulting configuration

3
paper-api/src/main/java/org/bukkit/configuration/file/YamlConfigurationOptions.java
View File

@@ -3,7 +3,8 @@ package org.bukkit.configuration.file;
import org.apache.commons.lang.Validate;
/**
* Various settings for controlling the input and output of a {@link YamlConfiguration}
* Various settings for controlling the input and output of a {@link
* YamlConfiguration}
*/
public class YamlConfigurationOptions extends FileConfigurationOptions {
private int indent = 2;