猫史档案馆

先看图

center_image

然后再看代码:

/**
 * @function 方块下坠
 * 标记一个(没有支撑的)方块, 并递归地让上方的方块下落
 * ```javascript
 * 注意, 在虚空会被当做空气计算, 因此不要指定y=0的方块!
 * ```
 * 
 * @param {number} x - x坐标
 * @param {number} y - y坐标
 * @param {number} z - z坐标
 * 
 * ### 模型图(■表示方块,▢表示空气, 纵坐标方向看作高度, y为参数中的y):
 * 
 * ```javascript
 * ...          `↓第二步是处理时的步骤, 正常情况不会显示`
 * y + 1   ■  >  ■  >  ▢
 * y + 0   ■  >  ▢  >  ■
 * y - 1   ▢  >  ■  >  ■
 * ...
 * ```
 * @example 简单例子
 * ```javascript
 * fallBlock(喵,2,喵)
 * ```
 * 
 */
function fallBlock(x, y, z) {
    //内部代码省略
}

(没错注释比代码还长)

这里就要介绍我们的主角: JSDoc

JSDoc是一种JS注释的规范, 标志就是第一行以/**开头, 下面每行开头都是*, 最后一行是*/ 的格式, 其中@function,@param被称为标签, 有着不同的含义, 而在Monaco Editor编辑器引擎中, 注释中也是可以使用markdown语法的(部分语法因为Box3奇特的加载模式而会显示异常), 这里面用到的几个标签有: @function(函数) @param(参数) @example(示例), 这些也不是乱填的, @function 其实是@kind function的别名, 而@param可以标记参数, 后面的大括号中就是参数类型, - 后面就是参数的描述, 最棒的是, 当你鼠标悬浮在对应参数或者调用函数的时候输入对应参数, 就会给出对应的提示, 如下图:

center_image