Comment spécifier et dans les paramètres?

Question

J'écris du javadoc, et je me demandais comment mettre en valeur un paramètre out.

Je suis actuellement faire (assez simple)

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

Votre javadoc regarde bien pour moi. clair et compréhensible. Ne pas oublier d'ajouter que les listes ont à créer et ont pour être moodifiable, sinon la méthode pourrait se plaindre avec de vilaines exceptions. Voilà pour la réponse.

Mais je vous suggère de ne pas utiliser les paramètres out à moins que vous ne soyez obligé de le faire (comme si vous deviez implémenter des interfaces tierces ou utiliser JNDI).

La méthode est nommée getNodes donc la plupart des programmeurs s'attendent à ce que la méthode renvoie un tableau ou une collection de noeuds. Mais dans ce cas, la méthode remplit deux listes passées avec des nœuds et des holotypes.

Donc, si votre libre de choisir la signature de la méthode, je vous suggère de le déclarer comme ceci:

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

ou déclarer un type spécial pour la classe, comme:

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

et mettre en œuvre la méthode comme ceci:

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

---

Si vous avez besoin de retourner deux listes (comme je l'ai lu dans les commentaires ci-dessus), une autre solution facile pourrait être envelopper les deux listes dans une carte:

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

à proprement parler, vous ne pouvez pas mettre en œuvre des paramètres OUT en Java. Tous les paramètres sont IN et sont passés par valeur ... où la valeur est une référence pour les types de référence.

Dans votre exemple, les paramètres semblent se comporter plutôt comme des paramètres OUT car il s'agit de collections mutables. Mais c'est une illusion. Par exemple:

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

Maintenant, si vous vous sentez comme étiqueter ces paramètres « IN » et les paramètres « OUT » dans la documentation de votre projet, c'est très bien (à condition que vous documentez clairement ce que vous entendez par les étiquettes).

Mais vous ne verrez normalement pas cette terminologie utilisée dans javadocs, car à proprement parler c'est incorrect ... par rapport à la terminologie standard enseignée dans les cours de langue de programmation comparatifs depuis au moins les années 1970.

Answer 3

Vous pouvez créer des annotations d'entrée et de sortie. Annoter ces annotations avec l'annotation Documentée. Je pense que vous pouvez appliquer des annotations aux paramètres dans le dernier JAVA. (Si vous ne pouvez pas ignorer cette réponse.) Ces annotations devraient apparaître dans vos javadocs.