JavaDoc'ta ayarlayıcıları/alıcıları, özellikleri ve yapıcıları belgelerken belge çoğaltmasından kaçınmanın bir yolu var mı?

Question

Gerçekten iyi belgelenmiş kodları severim. Ancak, dokümantasyonda çok sayıda kopya vardır, çünkü temel bilgiler ve örnekler, setterler/alıcılar ve yapıcılar için kullanılabilir olmalıdır (ayrıca bkz. Simple Getter/Setter comments).

JavaDocs'ların çoğaltılmasını önlemek için bir yol var mı? Sahip olduğum tek fikir, {@link #function()} kullanıyor ve daha fazla bilgi içeren JavaDocs'daki bir parçaya bağlantı veriyor.

package com.stackoverflow.tests; 

/** 
* An Event ... 
*/ 
public class Event { 

    /** 
    * The date the event takes place. 
    * Needs to be in <a href="https://en.wikipedia.org/wiki/ISO_8601">ISO 8601</a> format. 
    * 
    * <h2>Examples:</h2> 
    * <ul> 
    * <li>{@code 2016-03-19}</li> 
    * <li>{@code 2016-03-19T05:54:01+00:00}</li> 
    * <li>{@code 2016-W11} - i.e. week 11 of 2016</li> 
    * </ul> 
    */ 
    private String date; 

    /** 
    * Creates an event initializing it with the date and location the event takes place. 
    * @param date 
    * Date in <a href="https://en.wikipedia.org/wiki/ISO_8601">ISO 8601</a> format. Examples: 
    * <ul> 
    *  <li>{@code 2016-03-19}</li> 
    *  <li>{@code 2016-03-19T05:54:01+00:00}</li> 
    *  <li>{@code 2016-W11} - i.e. week 11 of 2016</li> 
    * </ul> 
    * @param location 
    * Location ... 
    */ 
    public Event(final String date, final String location) { 
    this.date = date; 
    } 

    /** 
    * The date the event takes place. 
    * @return 
    * Date in <a href="https://en.wikipedia.org/wiki/ISO_8601">ISO 8601</a> format. 
    */ 
    public String getDate() { 
    return date; 
    } 

    /** 
    * Updates the date the event takes place using an ISO 8601 formatted String. 
    * @param date 
    * Date in <a href="https://en.wikipedia.org/wiki/ISO_8601">ISO 8601</a> format. Examples: 
    * <ul> 
    *  <li>{@code 2016-03-19}</li> 
    *  <li>{@code 2016-03-19T05:54:01+00:00}</li> 
    *  <li>{@code 2016-W11} - i.e. week 11 of 2016</li> 
    * </ul> 
    */ 
    public void setDate(String date) { 
    this.date = date; 
    } 

} 

Answer 1

@link bir seçenektir, ama @see ek açıklama kullanmayı tercih ediyorum:

İşte hayali bir örnektir

@see "string" 

dize için bir metin girişi ekler. Bağlantı oluşturulmaz. Dize, URL tarafından bulunmayan bilgiler için bir kitap veya başka bir referanstır. Javadoc aracı ilk karakter olarak çift tırnak işareti (") arayarak önceki vakalarda bu ayırır. URL # değeri tarafından tanımlanan

@see <a href="URL#value">label</a> 

bir bağlantı ekler. URL # değeridir bir akraba veya mutlak URL'si. Javadoc aracı ilk karakter olarak bir az daha sembolü (<) bakarak diğer durumlarda bu ayırır.

---

sana özel olarak yararlıdır bunu bulacaksınız düşünüyorum, sen CA Standart belirleyiciler/getters yorumları için n link ve yinelenen bilgileri önlemek.

@see package.class#member label 

, fark edilebilir bir metin etiketine sahip bir bağlantı ekler başvurulmaktadır Java programlama dili belirtilen isim belgelerine puan söyledi.

Typical forms for @see package.class#member 
Referencing a member of the current class 
@see #field 
@see #method(Type, Type,...) 
@see #method(Type argname, Type argname,...) 
@see #constructor(Type, Type,...) 
@see #constructor(Type argname, Type argname,...) 

Referencing another class in the current or imported packages 
@see Class#field 
@see Class#method(Type, Type,...) 
@see Class#method(Type argname, Type argname,...) 
@see Class#constructor(Type, Type,...) 
@see Class#constructor(Type argname, Type argname,...) 
@see Class.NestedClass 
@see Class 

Referencing an element in another package (fully qualified) 
@see package.Class#field 
@see package.Class#method(Type, Type,...) 
@see package.Class#method(Type argname, Type argname,...) 
@see package.Class#constructor(Type, Type,...) 
@see package.Class#constructor(Type argname, Type argname,...) 
@see package.Class.NestedClass 
@see package.Class 
@see package