Question

我正在编写一些javadoc，并想知道如何强调out参数。

我目前正在这样做（非常简单）

/**
 * @param cl        (IN Parameter)  description here <br/>
 * @param nodes     (OUT Parameter) description here <br/>
 * @param holotypes (OUT Parameter) description here <br/>
 */
public void getNodes(List<O> cl, List<Node<O>> nodes, List<O> holotypes) {...}

Answer 1

严格来说，您无法在Java中实现OUT参数。所有参数都是IN并通过值传递...其中值是引用类型的引用。

在您的示例中，参数似乎的行为与OUT参数相似，因为它们是可变集合。但这是一种幻觉。例如：

    res = null;
    make(res);
    assert res != null;  // this would succeed with a real OUT parameter

    public void make(List<String> p /* OUT parameter */) {
        p = new ArrayList<String>();
    }

现在，如果您想在项目文档中标记这些参数“IN”和“OUT”参数，那很好（前提是您清楚地记录了标签的含义）。

但是你通常不会在javadocs中看到这个术语，因为严格来说它是不正确 ...相对于比较编程语言课程中教授的标准术语，至少从1970年代开始。< / p>

Answer 2

你的javadoc看起来很好。清楚易懂。不要忘记添加要创建的列表并且可以进行情境化，否则该方法可能会抱怨令人讨厌的异常。这么多答案。

但是我建议你不要使用out参数，除非你被迫这样做（比如你必须实现第三方接口或者你必须使用JNDI）。

该方法名为getNodes，因此大多数程序员都希望该方法返回一个数组或一组节点。但在这种情况下，该方法使用节点和holotypes填充两个传递的列表。

因此，如果你可以自由选择方法签名，我建议你这样声明：

public List<O> getNodes(List<O> cl) {
  List<O> result = pickAllNodesFromList(cl);
  return result;
}

public List<O> getHolotypes(List<O> cl) {
  List<O> result = pickAllHolotypesFromList(cl);
  return result;
}

或为该类声明一种特殊类型，例如：

class CLTypes<O> {
  List<O> nodes = new ArrayList<O>();
  List<O> holotypes = new ArrayList<O>();

  CLTypes(List<O> cl) {
    nodes.addAll(pickAllNodes(cl));
    holotypes.addAll(pickAllNodes(cl));
  }

  // getters for the nodes
  // ...

  // private methods to pick objects for source list
  // ...
}

并实现如下方法：

public CLTypes<O> getNodes(List<O> cl) {
  return new CLTypes<O>(cl);
}

如果您需要返回两个列表（正如我从上面的评论中读到的那样），另一个简单的解决方案可能是将两个列表包装在地图中：

public Map<String, List<O>> getNodes(List<O> cl) {
  Map<String, List<O>> result = new HashMap<String, List<O>>();
  result.put("nodes", pickAllNodes(cl));
  result.put("holotypes", pickAllHolotypes(cl));
  return result;
}

Answer 3

您可以在In和Out中创建注释。使用Documented注释注释这些注释。我认为你可以在最新的JAVA中对参数应用注释。（如果你不能忽略这个答案。）这些注释应该出现在你的javadoc中。

如何指定out和in参数？

3 个答案: