속성의 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;  
  }  

따라서 기본적으로 javadoc 주석을 복제하지 않고도 Eclipse IDE가 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;
    }
}

Lombok 은 이러한 작업에 매우 편리한 라이브러리입니다.

@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;
}

그게 전부입니다! @Getter주석은 각 개인 필드에 대한 getter 메소드를 생성하고 여기에 javadoc에 연결합니다.

추신 : 라이브러리에는 체크 아웃하고 싶을 수있는 멋진 기능이 많이 있습니다.

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;
}

마지막으로 해당 문서를 setter에 복사합니다.

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

그런 다음 수정하고 Eclipse 자동 완성을 사용하면 @param 태그뿐만 아니라 매개 변수 이름도 얻을 수 있습니다.

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

이제 끝났습니다. 내 생각에이 템플릿은 반복을 통해 속성이 의미하는 바를 기억할 수있을뿐만 아니라 측면을 추가하려는 경우 getter 및 setter에 추가 주석을 더 쉽게 추가 할 수 있도록 장기적으로 훨씬 쉽게 만듭니다. 효과 (예 : null 속성 허용 안 함, 문자열을 대문자로 변경 등). 이 목적을 위해 Eclipse 플러그인을 만드는 것을 조사했지만 JDT에 대한 적절한 확장 점을 찾을 수 없어 포기했습니다.

문장이 항상 T로 시작하는 것은 아닙니다. 붙여 넣을 때 첫 글자 만 대문자로 표시하거나 다시 대문자로 표시해야합니다.

나는 그것이 문제라고 생각하며 공식 Javadoc 가이드 는 그것에 대해 아무것도 말하지 않습니다. C #은 속성 사용을 통해 우아한 방식으로이 문제를 해결할 수 있습니다 (C #로 코딩하지는 않지만 정말 멋진 기능이라고 생각합니다).

그러나 나는 추측이 있습니다 : someString이 무엇인지 설명해야한다면 코드에 대한``나쁜 작은 ''일 수 있습니다. SomeClass를 작성하여 someString을 입력해야 함을 의미 할 수 있으므로 SomeClass 문서에서 someString이 무엇인지 설명하고 getter / setter의 javadocs가 필요하지 않습니다.