Как уточнить и в параметрах? - PullRequest
Новая
       15

Как уточнить и в параметрах?

2 голосов
/ 12 августа 2010

Я пишу какой-то 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) {...}

Ответы [ 3 ]

6 голосов
/ 12 августа 2010

Строго говоря, вы не можете реализовать параметры OUT в Java.Все параметры имеют значение 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-х годов..

3 голосов
/ 12 августа 2010

Ваш Javadoc выглядит хорошо для меня. ясно и понятно. Не забудьте добавить, что списки имеют , которые нужно создать, и имеют , которые можно настраивать, иначе метод может пожаловаться на неприятные исключения. Вот тебе и ответ.

Но я предлагаю вам не использовать out параметры, если вы не обязаны это делать (например, если вам нужно реализовать сторонние интерфейсы или вы должны использовать JNDI).

Метод называется getNodes, поэтому большинство программистов ожидают, что метод возвращает массив или коллекцию узлов. Но в этом случае метод заполняет два переданных списка узлами и голотипами.

Так что, если вы можете свободно выбирать метод подписи, я предлагаю вам объявить его следующим образом: 

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;
}
0 голосов
/ 12 августа 2010

Вы можете создавать аннотации In и Out.Аннотируйте эти аннотации с документированной аннотацией.Я думаю , что вы можете применять аннотации к параметрам в самой последней версии JAVA.(Если вы не можете игнорировать этот ответ.) Эти аннотации должны отображаться в ваших javadocs.

...