Lien Javadoc vers la méthode dans une autre classe

238

Actuellement, je référence des méthodes dans d'autres classes avec cette syntaxe Javadoc:

@see {@link com.my.package.Class#method()}

Et dans ce que je comprends de la documentation, c'est la bonne façon de le faire. Mais maintenant, pour la partie amusante ou frustrante. Lorsque je génère ce javadoc, j'obtiens tout d'abord l'erreur suivante:

warning - Tag @see:illegal character: "123" in "{@link com.my.package.Class#method()}"
warning - Tag @see:illegal character: "64" in "{@link com.my.package.Class#method()}"
warning - Tag @see: reference not found: {@link com.my.package.Class#method()}

Le code HTML généré est le suivant:

"," <code>com.my.package.Class#method()}</code> ","

Et bien sûr, je n'ai aucun lien. Quelqu'un peut-il me dire ce qui se passe et des conseils sur la façon de résoudre ce problème?

Selon le tableau ASCII, les caractères 123 et 64 pour wold représentent {et @, alors pourquoi ces caractères ne sont-ils pas valides lorsque cette syntaxe est correcte selon la documentation?

java javadoc

— Robert
source

Juste pour vérifier ... avez-vous lu la documentation de Javadoc Generator? docs.oracle.com/javase/7/docs/technotes/tools/windows/…

— Diogo Moreira

Avez-vous importé com.my.package.Classdans la classe ce JavaDoc est écrit? La référence non trouvée semble étrange. D'un autre côté, je ne les ai jamais utilisés combinés mais il y a une chance que @seeet en @linkconflit les uns avec les autres, en prenant cela qui @seegénère sa propre seciton, cela ne me surprendrait pas.

— Fritz

@DiogoMoreira - Non, je n'ai pas lu sur le moteur, mais je vais le vérifier.

— Robert

@Gamb - Bien sûr, ce n'est pas mon entrée Javadoc réelle ;-) Oui, toutes les importations sont en place.

— Robert

Une erreur similaire se produit si vous mettez un lien hypertexte brut comme valeur pour la @seebalise dans votre javadoc. Pour y remédier dans ce cas, encapsulez l'hyperlien dans un élément d'ancrage html:/** @see <a href="http://example.com">Example</a> */

— cyber-moine

Réponses:

280

Pour la balise Javadoc @see, vous n'avez pas besoin d'utiliser @link; Javadoc créera un lien pour vous. Essayer

@see com.my.package.Class#method()

Voici plus d'informations sur @see.

— rgettman
source

Merci pour cela, je viens de tester cette solution et cela fonctionne très bien! Mais j'ai lu dans tellement d'endroits que vous devriez utiliser le lien voir pour que cela fonctionne, donc c'est un peu étrange ...

— Robert

Vous pouvez utiliser @linkdans d'autres endroits que Javadoc ne se transforme pas déjà en lien, par exemple dans la description de @param, dans la description de @return, dans la partie principale de la description, etc.

— rgettman

quand je viens d'essayer cela, il affiche la méthode en texte brut, il n'est pas cliquable comme mon @see pour une méthode locale.

— JesseBoyd

146

En dehors de cela @see, une manière plus générale de se référer à une autre classe et éventuellement à une méthode de cette classe est {@link somepackage.SomeClass#someMethod(paramTypes)}. Cela a l'avantage d'être utilisable au milieu d'une description javadoc.

De la documentation javadoc (description de la balise @link) :

Cette balise est très similaire à @see - les deux nécessitent les mêmes références et acceptent exactement la même syntaxe pour package.class # member et label. La principale différence est que {@link} génère un lien en ligne plutôt que de placer le lien dans la section "Voir aussi". De plus, la balise {@link} commence et se termine par des accolades pour la séparer du reste du texte en ligne.

— Javarome
source

Ainsi, la solution au problème d'origine est que vous n'avez pas besoin des références "@see" et "{@link ...}" sur la même ligne. La balise "@link" est autosuffisante et, comme indiqué, vous pouvez la placer n'importe où dans le bloc javadoc. Vous pouvez donc mélanger les deux approches:

/**
 * some javadoc stuff
 * {@link com.my.package.Class#method()}
 * more stuff
 * @see com.my.package.AnotherClass
 */

— Dave Hentchel
source

Cette réponse devrait être acceptée car les deux autres réponses ne montrent pas que '@link' ou '@see' doivent être dans un commentaire sur plusieurs lignes / ** * / pas sur une seule ligne

— Stoycho Andreev

@Sniper, {@link }fonctionne très bien dans un commentaire Javadoc à une seule ligne, faites-vous peut-être référence au fait qu'ils ne fonctionnent pas avec les commentaires commençant par //? /** */est Javadoc et est nécessaire pour toutes les fonctions Javadoc.

— Jase

Oui @Jase J'ai rencontré exactement cela, le commentaire doit être / ** * /, mais pas //

— Stoycho Andreev

@Sniper Je ne pense pas que cela nécessite que ce soit la réponse acceptée car c'est une question Javadoc pour commencer - il devrait être généralement compris que Javadoc ne fonctionne que dans les commentaires Javadoc.

— Jase

@Jase est d'accord avec vous, mais je pense que la source d'informations comme Stackoverflow a besoin d'explications par des exemples et non des citations de la documentation Oracle ou d'une autre documentation, ce qui n'est pas clair de toute évidence. Cette réponse est la seule réponse qui a un exemple, au-dessus de deux réponses sont des guillemets.

— Stoycho Andreev