Senin ne olduğunu . ben^>teknikbüyük Javadoc yazma için ipuçları?

Bir şeyler arıyorumötesindestandart "işlevini de Açıklar" içerik tabanlı ipuçları. Bunu hepimiz biliyoruz! (değil mi?)

Bu gibi şeylerle ilgileniyorum

• Etiketleri kesinlikle olanları hatırlamaya değer olmayan bir Javadoc ve bir parçası olmak için ne yapmalıyım?
• @see vs {@link} kullanıyor musunuz?
• Her zaman belirli parametreler için @param kullanmak gerekli midir?
• Nasıl re-yineleme @param @return metinden bir yöntem açıklaması engellerim?
• Ne zaman Javadoc HTML eklemek için uygun mu?

Son olarak, herkes Javadoc etiketleri İyi, Kısa ve öz bir liste için bir işaret olabilir mi?

Ben şeflik benim Doktora araştırma kullanılabilirlik JavaDocs ve benim bulgular aslında gidip karşı "resmi kurallar" tarafından sağlanan Güneş (belge her şey ve belge iyi), ve destek sağlamak için "çevik" yaklaşımı (ne yazmak faydalı).

Özetle, sorun şu: ne zaman yazdığın her şey, aslında yazılı bir şartname ayrıntılı bilgi olacak izin veren biri var "umurunda değil" öğrenmek her şey hakkında bir işlev ve muhtemelen yaz tam bir test planı. Birçok uygulama için önemlidir.

ANCAK, her gün gelişim senaryoları, hiçbir geliştirici aslında vakit geçirmek için temin ettiğin her şey (bu sayılar gösterebilirim) okumaya gidiyor. Yağsız olacak, ve bilgi giremeyecek.

Genellikle, iletişim kurmak için en önemli olan şeyleri direktifleri - ve talimatlar veya uyarılar ve diğer bilgiler. sürpriz yapma genellikle Sadece bazı yöntemler ifade bu, ve genellikle özellikleri arasında kaybolur.

Ayrıntılı JavaDocs yazarak etkili bir şekilde önemli direktifleri gizleme ve tüketilen olacağını şansını azaltıyor. Kullanıcılar ayrıca çok uzun süre bakmak JavaDocs okuma önlemek eğilimindedir.

Bu sorun için benim yaklaşım direktifleri açık etiketleme ile, bir kullanıcı JavaDocs kaymağını onları göremez. Sitemde etiketlerin bir listesi var.

Ben de direktifleri olan aramalar vurgular tool adlı bir eMoose gelişmiş, ve iyi laboratuvar sonuçlarını alıyoruz ve EclipseCon de bu sene hediye edeceğiz. Eğer ben bu sayının daha fazla isterseniz bana ulaşın.

Eğer her şeyi belgeleyen, Güneş gözlükleri göre git gidersen, ama daha belirgin şeyler belgelenmesi anlamına gelir. özellikle seni sordu ne gelince: Zarar beri HTML ekleme kaçının, okunabilirlik bir IDE kullanmadan. Kitap "Temiz Kod" belgeleri üzerinde büyük bir bölüm vardır.

Burada birçok API araştırarak gerekli bulduk özel kategori:

• kullanımı.kısıtlama - Yasaklar kullanım yöntemi, belirli bağlamlarda (örneğin, "sakın çağırma dan UI iş parçacığı") veya tanımlar varlıklar yapmak için izin verilir çağırma (örneğin, "demem sadece hata ayıklama alt yapısı")

• kullanımı.protokol - bazı çağırma sırası Taşır. Örneğin "X karıştırdın önce bu çağırmak yok" veya "bu çağrıldıktan sonra Y bildirmek için".

• kullanımı.diş çekme - bazı sorunları iş parçacığı, bir sistem iş parçacığı kullanımını gerektiren veya yürütme engelleyebilir gösteren gibi ilgili Aktarıyor.

• kullanımı.kilitleme - kilitleme belirli gereksinimleri Aktarıyor

• kullanımı.performans - bu yöntemi kullanarak bazı performans sorunu var o istemciye İletir. Örneğin, bu çok zaman alır

• kullanımı.parametre dönüş değeri, kaldırma gibi sorumluluklar hakkında özel talimatlar Veriyor. Önemsiz şeyler için (olanlar için @param etiketini kullanın) kullanmayın.

• kullanımı.geri dönüş değeri, kaldırma gibi sorumluluklar hakkında özel talimatlar Veriyor. Önemsiz şeyler için (@return etiketini kullanın) kullanmayın.

• kullanımı.yan etkisi - bazı yan etkisi bu yöntem çağırma ile ilgili kullanıcıyı Uyarır

• kullanımı.güvenlik bazı güvenlik sorunları veya gereksinimleri bu yöntem çağırma ile ilgili kullanıcıyı Uyarır.

• kullanımı.alternatif - farklı bir yöntem kullanmak isteyebilirsiniz kullanıcılara Aktarıyor. Örneğin, "yenilemesini, X aramak yerine".

• kullanımı.öneri - ek işlemleri gerçekleştirmek için gerekli olan kullanıcılara Aktarıyor. Örneğin, "URL ilk doğrulamak isteyebilirsiniz".

• kullanımı.sınırlama - yöntemi nasıl çalıştığını (beklenmeyen) bazı sınırlama için kullanıcıyı Uyarır. Örneğin, "dinleyiciler için değişiklik bildirmez"

• kullanımı.patternrole - yöntem veya sınıf bir desen parçası olduğunu kullanıcıya Aktarıyor. Nadiren kullanılır.

• kullanımı.dernek - yöntem veya sınıf başka bir varlık ile ilişkili olan kullanıcıya Aktarıyor. Nadiren kullanılır.

Aşağıda ben yapıştırma bir fotoğrafın ne aracı gibi kullanmak: iki tagged şeyler JavaDoc bir yöntem, ve bir çağrı olduğunu bir kez daha gösterdi belirtmek hedefi olan bir yönerge.

[EDİT: eMoose Javadoc direktifleri güncellenmiş tam listesi (aşağıda) düz metin sürümü Eklendi*. *8] projeden

/*
@usage.general ...... No specific details
@usage.restriction .. Forbids the use of the method from certain contexts (e.g., "don't invoke from the UI thread") or defines the entities allowed to make the invocation (e.g., "To be called only from debug infrastructure")
@usage.protocol ..... Conveys some invocation sequence. For example "don't invoke this before you invoked X" or "remember to notify Y after calling this".
@usage.threading .... Conveys some issues relating to threading, such as requiring the use of a system thread or indicating that execution may block.
@usage.locking ...... Conveys specific locking requirements
@usage.performance .. Conveys to the client that there is some performance issue with using this method. For example, that it takes a lot of time
@usage.parameter .... Conveys specific instructions about the return value, such as deallocation responsibilities. Don't use this for trivial things (use the @param tag for those).
@usage.return ....... Conveys specific instructions about the return value, such as deallocation responsibilities. Don't use this for trivial things (use the @return tag for those).
@usage.sideeffect ... Alerts the user to some sideeffect associated with invoking this method
@usage.security ..... Alerts the user to some security implications or requirements associated with invoking this method.
@usage.alternative .. Conveys to the users that they may want to use a different method. For example, "to cause a refresh, call X instead".
@usage.recommendation Conveys to the users that they may want to perform additional operations. For example, "you may want to validate the URL first".
@usage.limitation ... Alerts the user to some (unexpected) limitation in how the method works. For example, "does not announce changes to listeners"
@usage.patternrole .. Conveys to the user that the method or class is part of a pattern. Rarely used.
@usage.association .. Conveys to the user that the method or class is associated with some other entity. Rarely used.
@todo.task .......... Indicates a remaining action item that would constitute an entire task (relevant primarily to full version)
@todo.step .......... Indicates a remaining item that would constitute a mere step in an entire task (relevant primarily to full version)
@todo.local ......... Indicates a small action item relevant to the current location. Essentially equivalent to a //todo comment
@todo.lookout ....... Indicates a need to be watchful for something in the future (relevant primarily to full version)
@todo.refactor ...... Indicates a need to refactor the material at the current location
@todo.optimize ...... Indicates a need to optimize the material at the current location.
@bug.general ........ General bug
@bug.task ........... Indicates a bug in the current task (relevant primarily to full version)
@bug.unrelated ...... Bug unrelated to current task (relevant primarily to full version)
@bug.resolved ....... Indicates that a bug has been resolved in this location
@bug.filed .......... Indicates that a certain bug (with given information) has been filed at this location
*/