Bukkit 中文文档

提示： 该分支(master)用于进行Bukkit 1.13及以上版本的翻译工作。
限于作者精力，1.12.2版本已于2019.9.19正式停更，且不再提供1.12.2版本的在线文档。
您依然可以前往1.12.2分支查看相关代码，但不对历史文档中的错误负责。
文档地址：https://bukkit.windit.net/javadoc/ (可以应用于IDE，在IDE中实时预览)
离线版：1.12.2版本 | 1.13及以上版本
宣传：欢迎加入汉化组开发讨论QQ群：459574218。您可以与业内各界人士畅谈coding经验与想法. (加群注明来源:来自github代码仓库)
遇到问题请发Issues或PR，以帮助我们解决相关问题。

项目说明

本项目的目标是翻译BukkitAPI的Javadoc，推进中国原创MC插件的发展，项目由andylizi发起。

Javadoc注释规范

Javadoc是JDK提供的一个工具，它可以从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的API帮助文档。
在开始翻译前, 请先掌握Javadoc文档注释样式. 参阅:
1.http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html (英文)
2.http://www.cnblogs.com/xt0810/p/3630996.html

许可说明

本文档的翻译部分使用CC BY-NC 4.0许可协议发布，您不得将任何译文出于商业化的目的而使用。其它所有源代码属SpigotMC所有，以GPLv3许可协议发布.

翻译规范

原文保留

为了使文档更严谨、方便比对，必须保留原文。例如：

/**
 * 获取世界当前的PVP设置. 
 * <p>
 * 原文：
 * Gets the current PVP setting for this world.
 *
 * @return 如果允许PVP则返回true
 */
public boolean getPVP();

分为三部分, 第一部分为简述: 使用简短的语言描述的用途.
使用 . 号加一个空格给简述结尾. JavaDoc工具使用". "(英文句号后跟一个空格)来区分简单描述与详细描述, 但不会自动在这两种描述之间添加换行

请统一使用英文标点符号.

第二部分为详细描述, 用于详细说明方法用途, 或举一些简单的例子.

第三部分为JavaDoc标签, 其中有: 参数说明 @param, 返回值说明 @return, 抛出异常说明 @throws 等, 后面会详细说明.

请在需要换行的地方请使用 <p> 否则不会换行

原文与译文必须是连贯的，译文一句原文一句是错误的。 例外：类注释、枚举注释、标签一般不需要保留原文，若是比较难懂的、一大串的则需要保留。

类注释

类注释即为类的描述，介绍了类的作用等，比如：

/**
 * Represents a Command, which executes various tasks upon user input
 */
public abstract class Command {
  ...
}

枚举注释

即枚举类中对一些字段的注释，例如：

/**
 * 橡树
 */
TREE,
...

方法注释

一个例子：

/**
 * (1)Checks if this player is currently online
 *
 * (2)@return true if they are online
 */
public boolean isOnline();

(1)处为方法的描述，是需要翻译的地方。 (2)处为javadoc的标签，javadoc的标签以"@"开头，对应的标签就有对应的说明。关于标签在下一部分详细说明。 如果注释中出现了你不能理解的内容，或翻译过来难以理解，请在原文之前加上译注，用自己的理解继续说明，比如：

/**
 * 获取指定坐标的最顶上的方块的Y坐标(不是空气).  
 * 
 * 译注：意思是获取某个坐标最上面的方块的高度(Y坐标). Essentials插件的top命令就是这个原理.
 * 原文：Gets the highest non-air coordinate at the given coordinates
 *
 * @param x 给定的X坐标
 * @param z 给定的Z坐标
 * @return 在x,y位置的最高的方块的高度(忽略空气)
 */
public int getHighestBlockYAt(int x, int z);

标签

你之前已经了解了一些javadoc的标签，比如@param、@return、@see、@deprecated等等，这里详细解释下一些特别的标签该如何翻译：

@param 参数名 参数说明

@param loc 一个位置({@link Location})

注意: 参数名不用翻译, 对应的是方法中的参数.

@return 返回值说明

@return 此方块的位置

@throws 异常类型 在什么情况下会抛出这个异常

@throws IllegalArgumentException 如果PlayerListName超过16个字符

注意别把异常的类名去掉. @throws 标签的说明通常以"if"或"如果"开头.

@deprecated 原因

这个标签代表此方法已过时被弃用/不推荐使用, 并说明了原因.
例如 java.awt.Window 类中的 show() 方法:

    /**
     * 使窗口可见. 
     * 如果窗口和/或其所有者还不能显示, 则都不显示. 
     * 在使窗口可见之前将验证它. 如果窗口已经可见, 则此方法将窗口带到最前面. 
     * 
     * @see Component#isDisplayable
     * @see #toFront
     * @deprecated 从 JDK 1.5 版开始, 由 {@link #setVisible(boolean)} 取代. 
     */
    @Deprecated
    public void show(); 

BukkitAPI中出现的大部分 @deprecated 标签一般是这样的

@deprecated Magic value

Magic value具体是什么意思有点难以解释, 请查阅百度百科 "Magic number" 里 "程序开发中的含义".
一般出现在 getTypeId() setTypeId() setData() 一类的"方法参数或返回值使用数字来表示类型"的方法.
为什么不推荐使用? 因为如果使用这些数字, 那么你的代码看起来会是这样的:

block.setTypeId(137);

阅读代码的人: "把这个方块的类型设为..诶等等, 137是哪个方块? 我去查查方块列表..哦原来是命令方块啊"
如果不使用ID而使用 Material 枚举

block.setType(Material.COMMAND_BLOCK);

阅读代码的人: "一看就明白这代码的意思是把这个方块的类型设置为命令方块"

@see 另请参见

不必翻译.

@since 版本号

自从哪个版本加入的这个成员.
如果只有一个版本号, 不必翻译.

{@link 类名#成员名}

在最终生成的JavaDoc里添加一个指向某类中某成员的超链接.
如果此文档注释所在的类有 import, 那么@link 里无需写包名, 例如

    import org.bukkit.Location;
    
    //....此处略
    
    /**
     * 获得此方块所在的{@link Location}.  
     /
    public Location getLocation();

但如果没有 import, 则必须写全名

获得此方块所在的 {@link org.bukkit.Location}.

想指向某类里具体的成员(例如方法, 字段等), 可以使用 #

@deprecated 请使用 {@link Block#getType()} 方法代替

如果成员所在的类就是本类还可以简写为

@deprecated 请使用 {@link #getType()} 方法代替

如果有多个名字一样的重载方法可在括号内加参数类型

@deprecated 从 JDK 1.5 版开始, 由 {@link Window#setVisible(boolean)} 取代.

{@linkplain 类名#成员名 显示名}

跟 @link 相似, 但区别是可以自定义显示的名称. 显示名称需要进行翻译.
(注: @link 也是可以定义显示名的, 所以在某种意义上 @link 与 @linkplain 功能是一样的, 但在 @link 里定义显示名并不是规范的用法.)

获得此 {@link org.bukkit.Block} 的类型, 如果为空气则返回 {@linkplain Material#AIR AIR}.

会被JavaDoc工具解析为

获得此 <a href="Block.html">Block</a> 的类型, 如果为空气则返回 <a href="Material.html#AIR">AIR</a>.   

译名标准

对于 Minecraft 上的名词, 如果你不知道其确切的意义, 可以参考译名标准化 和 1.13 扁平化. 尽量使用官译名.

翻译须知

翻译质量

严禁直接机翻, 若实在不会请以单词和句子结构为单位进行查询, 加入自己的理解, 重新组织语言. 否则将撤回 为什么要以单词为单位? 因为也许电脑程序能当成一本合格的字典来使用, 但绝无法进行合理的语法组织.

遇到问题？

如果您翻译时遇到了某些您不能理解的单词、专有名词、段落、概念等等，欢迎在群内提问, 在不能肯定的情况下请别擅下定论.

提交翻译

Fork本项目并作出您的修改，之后向我们发 Pull Request. 或者您可以申请成员权限，成为成员后可以自由编辑.