Javadoc @see veya {@link}?

184

Birisi bana javadoc @seeve arasındaki farkı söyleyebilir {@link}mi?

Daha doğrusu hangisini ne zaman kullanmalı?

java javadoc

— membersound
kaynak

213

Bununla ilgili resmi yönergeler oldukça açıktır.

İşlevsel farklılıklar şunlardır:

{@link} satır içi bir bağlantıdır ve istediğiniz yere yerleştirilebilir
@see kendi bölümünü oluşturur

Bence {@link}en iyi, açıklamanızda bir sınıf, alan, kurucu veya yöntem adı kullandığınızda kullanılır. Kullanıcı, bağladığınız şeyin javadokosuna tıklayabilecektir.

Kullandığım @see2 olguda ek açıklama:

Bir şey çok alakalı, ancak açıklamada belirtilmemiş.
Aynı şeye açıklamada birçok kez atıfta bulunuyorum ve aynı çoklu bağlantıların yerine geçiyor.

Bu görüşü, standart kütüphanedeki çok çeşitli şeyler için belgeleri rastgele kontrol etmeye dayandım.

— MarioDS
kaynak

3

Javadoc, @link'in oldukça yoğun olduğu ve yalnızca gerektiğinde kullanılması gerektiği konusunda uyarır.

— Thomas

4

Arayan herkes için @link, Oracle'ın Javadoc rehberinde bununla ilgili ayrıntıları ( yukarıdaki yorumda yer alan uyarı da dahil olmak üzere ) alabilirsiniz .

— Ash Ryan Arnwine

48

@seeJavadoclarda yalıtılmış bir çizgi oluşturur. {@link}metnin içine gömmek içindir.

@seeİlişkili bir varlık olduğunda kullanıyorum ancak açıklayıcı metinde bunu belirtmiyorum. Sıkı bir bağlantı olduğunda metin içindeki bağlantıları kullanıyorum veya (hissediyorum) okuyucunun gezinme ipucundan faydalanması muhtemeldir, örneğin, doğrudan referans vermeniz gerekir.

— Dave Newton
kaynak

3

Aynı resmi dokümanlar üzerinde tercih edilen başka bir referans (kullanımdan kaldırma bölümü) {@link}var @see(Java 1.2'den beri):

Javadoc 1.2 ve sonraki sürümler için standart biçim @deprecated etiketini ve satır içi {@link} etiketini kullanmaktır. Bu, bağlantıyı istediğiniz yerde satır içinde oluşturur. Örneğin:

Javadoc 1.1 için standart biçim bir çift @deprecated ve @see etiketi oluşturmaktır. Örneğin:

— user7294900
kaynak