关于一个 Javadoc 风格的讨论，@param、@return 是否允许空描述，即是否必须总是有描述信息

有疑问的代码

    /**
     * ……
     * 
     * @param deviceNo
     * @return
     */
    public static EmbeddedChannel createChannel(String deviceNo) {
        // ....
    }

如果没有特别需要的额外说明，那么 deviceNo 一目了然就是指设备号码，写成 @param deviceNo device no 或 @param deviceNo 设备编号感觉就是脱裤子放屁。@return 同理。

然而 Google Java Style 只给 getFoo 这种方法做宽松限制，不给 @param @return 做。

Javadoc is optional for "simple, obvious" methods like getFoo, in cases where there really and truly is nothing else worthwhile to say but "Returns the foo".

Javadoc 对于像 getFoo 这样的“简单、明显”的方法是 可选的，在这种情况下除了“返回 foo ”之外真的没有什么值得说的。

Any of the standard "block tags" that are used appear in the order @param, @return, @throws, @deprecated, and these four types never appear with an empty description.

使用的任何标准“块标记”都以 @param、 @return、 @throws、 @deprecated 的顺序出现，并且这四种类型永远不会出现空描述。