[Item 19] 상속용 주석 @InheritDoc

[Limgayoung]

책을 쓰는 시점에는 일반적인 API 설명과 상속용 설명을 구분해주는 도구가 마땅치 않다고 했는데 @InheritDoc 애노테이션을 사용하면 구분해서 설명을 달 수 있습니다. 자세한 사용법과 주의사항을 설명한 사이트입니다.

https://medium.com/@gewzk/what-is-inheritdoc-in-java-with-example-300ad5566fbc

[ForteEscape]

• 해당 자료를 읽어보니 @inheritdoc 은 문서를 작성할 때 상위 클래스에 대한 설명을 하위 클래스에도 동일하게 제시해야할 때 사용되는 어노테이션으로 확인됩니다.

• 해당 어노테이션이 붙으면 상위 클래스의 메서드 document 설명을 가져오는 방식이기 때문에 상속용 설명이라기 보다는 하위 클래스 메서드의 설명이 상위 클래스의 설명과 동일한 경우에서 유용하게 사용될 수 있습니다. 또한 상위 클래스에서 document의 설명이 달라지는 경우에, 이를 동기화하기 위한 목적으로도 사용됩니다.

  • 즉 설명을 상속하는 것으로 생각됩니다.

• 하지만 책에서 설명하는 상속용 설명과는 조금 어긋나는 것 같습니다. 책에서 제시하는 상속용 설명은 상속시에 주의할 점과 해당 메서드가 상속 시 어떻게 동작하는지, 내부 동작 원리를 설명하는 것입니다. 아쉽게도 현재 java의 최신 장기 지원 버전인 JDK 21까지도 해당 설명을 구분해줄 수 있는 document comment는 나오지 않은 것으로 확인됩니다.

• 위의 링크 와 Java 공식 문서 도 참고하시면 좋을 것 같습니다.

[Limgayoung]

말씀하신 것처럼 책에서 상속용 메서드에 주석을 달 때에는 오버라이딩 할 때의 주의점, 동작 원리 등을 작성해야 한다고 했습니다. @inheritDoc을 이용한다면 이런 주의점을 하위 클래스에 계속 제시할 수 있기 때문에 상속용 설명이 필요할 경우에는 항상 이 어노테이션을 사용하는 것이 좋아 보였습니다.

하지만 주석이 어디에서부터 전달되어 온 것인지 모호할 수 있고, 단순히 일반 주석과 구분하기 위한 용도(책에서 원하는)로 사용하기에는 무거운 것 같긴 합니다.