Как указать параметры и параметры?

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

Ваш 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; 
} 

Answer 2

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

Answer 3

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