JavaDoc'ta @see kullanımı?

110

Ne zaman kullanabilirim @seejavadocs uğraşırken? Kullanımı nedir?

Örneğin eğer MethodAçağrılar MethodBsonra ben koymak zorunda yapmak @seeiçinde MethodB'nin javadoc ve referans MethodAişte bu dediği çünkü ya ben bir başvuru gerekiyor mu MethodBdan MethodAonu aradığını çünkü. @seeOracle web sitesindeki bilgileri okudum ve bana inanılmaz derecede belirsiz görünüyor, "ayrıca bakın" anlamına geldiğini söylüyor, ancak bunun gerçekten ne anlama geldiği değil!

java methods javadoc

— Jeff
kaynak

4

koymak @seeiçinde MethodBjavadoc ve referans 'ın MethodAbu kadar dediği çünkü > hiç mümkün olacağını nasıl yöntemlerinden birini çağırmak tüm yöntemleri bilmek -? Bu mümkün olsa bile (sadece bir kez kullanılan özel bir yöntem diyelim) arayan uçtan arayanla bağlantı kurmak en azından garip geliyor ...

— Mr_and_Mrs_D

1

: Bu genellikle İngilizce olarak ne anlama geldiğini demektir oxforddictionaries.com/us/definition/american_english/see (çözünürlüklü 1.4)

— stackexchanger

119

Evet, oldukça belirsiz.

Yönteminizin dokümantasyonunun okuyucuları için her zaman kullanmalısınız, başka bir yönteme de bakmak yararlı olabilir. MetodA'nızın dokümantasyonu "methodB gibi çalışıyor ama ..." diyorsa, o zaman mutlaka bir bağlantı koymalısınız. @seeSatır içi {@link ...}etiket için bir alternatif olabilir :

/**
 * ...
 * Works like {@link #methodB}, but ...
 */

MethodA'nın methodB'yi çağırması gerçeği bir uygulama ayrıntısı olduğunda ve dışarıdan gerçek bir ilişki olmadığında, burada bir bağlantıya ihtiyacınız yoktur.

— Paŭlo Ebermann
kaynak

13

@see@Deprecatedyöntemlere alternatiflere bağlanmak için de yararlıdır .

— Mauve Ranger

1

@MauveRanger Bu yana @seeoldukça belirsiz, kullanımdan kaldırılan şeyler için daha açık bir şeyler yapmayı daha faydalı buluyorum, örneğin:@deprecated since X.Y.Z; use {@link #alternateMethod()} instead

— Christopher

10

@see, bir API'deki ilgili yöntemler / sınıflar hakkında bilgi için kullanışlıdır. Belgelerde başvurulan yöntem / koda bir bağlantı oluşturacaktır. Kullanıcının API'yi nasıl kullanacağını anlamasına yardımcı olabilecek ilgili kod olduğunda kullanın.

— Rob Dawson
kaynak

9

@seeYararlı olabileceği bir duruma iyi bir örnek, bir arayüz / soyut sınıf yöntemini uygulamak veya geçersiz kılmak olabilir. Bildirim javadoc, yöntemi detaylandıran bölüme sahip olacaktır ve geçersiz kılınan / uygulanan yöntem @see, temel olana atıfta bulunarak bir etiket kullanabilir .

İlgili soru: @see ile uygun javadoc yazmak?

Java SE belgeleri: @see

— AtomHeartFather
kaynak

2

ben değildim, ama muhtemelen @inheritDoc docs.oracle.com/javase/6/docs/technotes/tools/solaris/…

1

@see için java dokümantasyonu gerçekten iyi. ilk olmalı.

— dok

2

@vaxquis @inheritDocbelgeleri başka bir yerden kopyalar. Kabartmak yerine ayrıntıları açıklamanın faydaları olduğunu hayal ediyorum.

— Nielsvh

@Nielsvg bu cevap bundan bahsediyor the overridden/implemented method could use a @see tag, referring to the base one.- ve tam olarak @inheritDocbunun için; IMO vasıtasıyla aynen taban sınıfı açıklama içerecek şekilde daha iyi @inheritDoc ve gerektiği gibi tarafından kendisine atıfta yerine, onu tamamlayacak @see(sic!) - bakınız stackoverflow.com/questions/11121600/... ; birçok geliştirici (ben dahil) , bir miras hiyerarşisi aracılığıyla yukarı doğru giden yukarı doğru zincirlerden oluşan zincirleri hiç bitirmemek yerine, tüm uygulama ayrıntılarının tek bir yerde olmasını tercih ediyor .

2

Yöntemin açıklamasının zaten arabirimin javadoc'unda sağlandığı bir arabirim uygulama sınıfının yöntemlerine açıklama eklemek için @see kullanıyorum. Bunu yaptığımızda, kod tamamlama sırasında uygulama referansında yöntem ararken bile Eclipse'in arayüzün belgelerini açtığını fark ediyorum.

— Maruthi
kaynak