속성의 Javadoc을 작성하는 방법?

속성의 Javadoc을 작성하는 방법?

---

속성과 getter 및 setter (DTO 스타일) 만 보유하는 "간단한"POJO 클래스의 속성 / 멤버에 대한 javadoc을 작성할 때 종종 딜레마가 발생합니다 ....

1) 속성에 대한 javadoc 작성
또는 ...
2) getter에 대한 javadoc 작성

속성에 대한 javadoc을 작성하면 나중에 코드 완성을 통해 POJO에 액세스 할 때 내 IDE (Eclipse)가 (당연히) 이것을 표시 할 수 없습니다. 그리고 getter-javadoc를 실제 속성 javadoc에 연결할 수있는 표준 javadoc 태그가 없습니다.

예 :

public class SomeDomainClass {

  /**
   * The name of bla bla bla
   */
  private String name;

  /**
   * @return INSERT SOME SMART JAVADOC TAG LINKING TO name's javadoc
   */
  public String getName() {  
    return name;  
  }  

따라서 기본적으로 Eclipse IDE가 javadoc 주석을 복제하지 않고도 getter에 대한 javadoc 속성 설명을 표시하도록하는 방법을 듣는 것은 흥미로울 것입니다.

지금은 속성이 아닌 게터 만 문서화하는 연습을 고려하고 있습니다. 하지만 최선의 해결책은 아닌 것 같습니다 ...

---

Javadocs를 생성하는 동안 (-private 사용) 개인 구성원을 포함시킨 다음 @link를 사용하여 해당 필드 속성에 연결할 수 있습니다.

public class SomeDomainClass {
    /**
     * The name of bla bla bla
     */
    private String name;

    /**
     * {@link SomeDomainClass#name}
     */
    public String getName() {
        return name;
    }
}

또는 모든 개인 멤버에 대해 Javadoc을 생성하지 않으려면 모든 getter를 문서화하고 setter에서 @link를 사용하는 규칙을 가질 수 있습니다.

public class SomeDomainClass {
    private String name;

    /**
     * The name of bla bla bla
     */
    public String getName() {
        return name;
    }

    /**
     * {@link SomeDomainClass#getName}
     */
    public void setName(String name) {
        this.name = name;
    }
}

---

Eclipse의 자동 완성 기능을 사용하여 둘 다 수행합니다.

먼저 속성을 문서화합니다.

/**
 * The {@link String} instance representing something.
 */
private String someString;

그런 다음 이것을 복사하여 getter에 붙여 넣습니다.

/**
 * The {@link String} instance representing something.
 */
public String getSomeString() {
    return someString;
}

eclipse를 사용하면 @return 문에 자동 완성 기능이 있으므로 Gets라는 단어를 추가하고 "t"를 소문자로하고 소문자 "t"로 문장을 복사합니다. 그런 다음 @return (Eclipse 자동 완성 사용)을 사용하고 문장을 붙여 넣은 다음 리턴에서 T를 대문자로 사용합니다. 그러면 다음과 같이 보입니다.

/**
 * Gets the {@link String} instance representing something.
 * @return The {@link String} instance representing something.
 */
public String getSomeString() {
    return someString;
}

Finally, I copy that documentation to the setter:

/**
 * Gets the {@link String} instance representing something.
 * @return The {@link String} instance representing something.
 */
public void setSomeString(String someString) {
    this.someString = someString;
}

Then, I modify it and with Eclipse autocomplete you can get not only the @param tag but also the name of the parameter:

/**
 * Sets the {@link String} instance representing something.
 * @param someString The {@link String} instance representing something.
 */
public void setSomeString(String someString) {
    this.someString = someString;
}

Then, I'm done. In my opinion, this templating makes it a lot easier, in the long run, to not only remind yourself what the property means through repetition, but also it makes it easier to add additional comments to the getter and setter if you want to add side effects (such as not allowing null properties, turning strings to uppercase, etc). I investigated making an Eclipse plugin for this purpose but I couldn't find the appropriate extension point for the JDT, so I gave up.

Note that the sentence might not always start with a T - it's just the first letter has to be uncapitalized/recapitalized in pasting.

---

Lombok is a very convenient library for such tasks.

@Getter
@Setter
public class Example {
    /**
     * The account identifier (i.e. phone number, user name or email) to be identified for the account you're
     * requesting the name for
     */
    private String name;
}

That is all you need! The @Getter annotation creates a getter method for each private field and attach the javadoc to it.

PS: The library has many cool features you might want to checkout

---

I really think it's a problem and the official Javadoc guide does not tell anything about it. C# can solve this in an elegant fashion with the Properties usage (I don't code in C#, but I really think it's a nice feature).

But I have a guess: if you need to explain what someString is, maybe it is a ``bad small'' about your code. It can mean that you should write SomeClass to type someString, so you would explain what is someString in the SomeClass documentation, and just so the javadocs in getter/setter would be not necessary.

참고URL : https://stackoverflow.com/questions/2273170/how-to-write-javadoc-of-properties