속성 Javadoc 작성 방법

속성 Javadoc 작성 방법

속성/프로퍼티와 게터 및 세터(DTO 스타일)만 보유한 "심플한" POJO 클래스의 멤버에 대해 javadoc을 작성할 때 딜레마에 빠집니다.

1) 자산에 javadoc을 씁니다.
아니면...
2) getter에 javadoc을 씁니다.

속성에 javadoc을 쓰면 나중에 코드 완료를 통해 POJO에 접속할 때 IDE(Eclipse)에서 이를 표시할 수 없습니다.getter-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를 문서화하고 setters에서 @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;
    }
}

롬복 도서관은 이런 작업을 하기에 매우 편리한 도서관이다.

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

그것만 있으면 돼!그@Getterannotation은 각 개인 필드에 대해 getter 메서드를 만들고 javadoc을 연결합니다.

PS: 라이브러리에는 체크하고 싶은 멋진 기능이 많이 있습니다.

둘 다 이클립스의 오토컴플릿의 도움을 받아 해

먼저 속성을 기록합니다.

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

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

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

이클립스에서는 @return 스테이트먼트에 자동완성이 있기 때문에 Gets를 추가하고 t를 소문자로 한 후 문장을 t로 복사합니다.그런 다음 @return(이클립스 자동완료)을 사용하여 문장을 붙여넣고 반환 시 T를 대문자화합니다.그 후, 다음과 같이 됩니다.

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

마지막으로 이 문서를 설정자에게 복사합니다.

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

그런 다음 수정하면 Eclipse autocomplete를 사용하여 @param 태그뿐만 아니라 파라미터 이름도 얻을 수 있습니다.

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

그럼, 난 끝이야.내 생각에 이 템플릿은 장기적으로는 반복을 통해 속성이 무엇을 의미하는지 상기시키는 것이 훨씬 쉬워질 뿐만 아니라 부작용(null 속성을 허용하지 않거나 문자열을 대문자로 변환하는 등)을 추가하고 싶을 때 getter와 setter에 코멘트를 추가하는 것이 더 쉬워진다.이를 위해 이클립스 플러그인 작성을 검토했지만 JDT에 적합한 확장 포인트를 찾을 수 없어 포기했습니다.

문장이 항상 T로 시작하는 것은 아닙니다.붙여넣을 때 첫 글자는 대문자를 쓰지 않거나 다시 대문자를 써야 합니다.

나는 그것이 정말 문제라고 생각하고 자바독 공식 가이드는 그것에 대해 아무 말도 하지 않는다.C#은 Properties 사용법을 사용하여 우아하게 해결할 수 있습니다(C#은 코드화하지 않지만, 정말 좋은 기능이라고 생각합니다).

하지만 추측컨대, 만약 당신이 someString이 무엇인지 설명할 필요가 있다면, 그것은 당신의 코드에 대한 "나쁜 작은" 것일지도 모른다.즉, SomeClass를 작성하여 someString을 입력해야 하므로 SomeClass 문서에서 someString이 무엇인지 설명하고 getter/setter에서 javadocs가 필요하지 않습니다.

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