How to specify out and in parameters?

Question

I'm writing some javadoc, and was wondering how to emphasize an out parameter.

I'm currently doing this (pretty straightforward)

/**
 * @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

Strictly speaking you cannot implement OUT parameters in Java. All parameters are IN and are passed by value ... where the value is a reference for reference types.

In your example, the parameters seem to behave rather like OUT parameters because they are mutable collections. But this is an illusion. For example:

    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>();
    }

Now, if you feel like labelling these parameters "IN" and "OUT" parameters in your project documentation, that's fine (provided that you clearly document what you mean by the labels).

But you won't normally see this terminology used in javadocs, because strictly speaking it is incorrect ... relative to the standard terminology taught in comparative programming language courses since at least the 1970's.

Answer 2

Your javadoc looks fine to me. clear and understandable. Don't forget to add that the lists have to be created and have to be moodifiable, otherwise the method might complain with nasty exceptions. So much for the answer.

But I suggest you do not use out parameters unless you're forced to do so (like if you have to implement 3rd party interfaces or you have to use JNDI).

The method is named getNodes so most programmers expect, that the method returns an array or a collection of nodes. But in this case, the method populates two passed lists with nodes and holotypes.

So if your free to choose the method signature, I suggest you declare it like this:

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;
}

or declare a special type for the class, like:

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
  // ...
}

and implement the method like this:

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

---

If you need to return two lists (as I read from the comments above), another easy solution could be wrapping the two lists in a map:

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;
}