Javadoc : package.html 또는 package-info.java

230

패키지 레벨 Javadoc 주석을 작성하려고 할 때 선호되는 방법은 무엇입니까? 너 뭐하니?

package-info.java

찬성
- 최신
단점
- 수업의 남용-수업은 댓글 용이 아닌 코드 용입니다.

package.html

찬성
- HTML 확장은 코드가 아님을 의미합니다.
- IDE / 텍스트 편집기에서 구문 강조
단점
- 없어요?

필자는 항상 Package.html을 사용했습니다. 그러나 올바른 선택인지 궁금합니다.

java javadoc

— TheLQ
소스

package-info.java[패키지] 주석을 포함 할 수 있습니다. 반드시 모든 API 문서는 아닙니다.

— Tom Hawtin-tackline

package-info.java를 클래스의 남용으로 사용할 수 없습니다. Java 소스 파일 ( ".java"파일 확장자를 가짐)이지만 클래스 선언을 포함하지 않기 때문에 클래스 파일이 아닙니다. 실제로 "package-info"는 올바른 클래스 이름이 아니기 때문에 클래스 선언을 포함 할 수 없습니다.

— Scrubbie

package.html 대신 package-info.java를 사용하는 또 다른 이유는 .java가 문서의 특정 출력 형식을 의미하지 않기 때문입니다. 예를 들어, javadoc을 LaTeX 또는 PDF 파일로 출력 할 수 있습니다. javadoc 컴파일러 구현에 따라 .html 경우에 문제가 발생할 수 있습니다.

— honeyp0t

실제로 @Scrubbie-비록 옳 아야하지만 패키지-개인 클래스를 지정할 수 있다고 생각합니다. :-( package-info.javaJavadoc 및 주석에 사용 하는 것은 수업의 남용이 아닙니다.

— mjaggard

참조 @JonasN stackoverflow.com/a/14708381/751579을 (내가 3 년 전에이 문제를 가지고 알고 있지만, 다른 어쩌면 누군가는 이제 끝을 필요로)

— davidbak

269

package-info.java: "이 파일은 JDK 5.0의 새로운 파일이며 package.html보다 선호됩니다."— javadoc-Java API 문서 생성기

부록 : 큰 차이점은 패키지 주석 인 것 같습니다 . 7.4 패키지 선언 에는 이론적 근거가 조금 더 있습니다.

부록 : 주석 기능은 여기 및 여기 에서도 언급 됩니다 .

부록 참조 : 무엇 package-info.java을 위해? .

— 쓰레기
소스

선호하는 특별한 이유는 무엇입니까?

— TheLQ

@ TheLQ : 컴파일러가 작업 할 더 많은 정보를 가지고 있기 때문에 패키지 주석을 추측하고 있습니다. 더 위.

— trashgod

패키지 주석은 나에게 새롭고, 그 범위로 인해 package-info.java의 좋은 이유처럼 보입니다.

— 스태커

"패키지 주석"을 설명하십시오-패키지의 모든 클래스 또는 패키지 전체에 적용되는 주석입니다. tech.puredanger.com 링크는 내가 왜 관심을 가져야 하는지를 실제로 설명 할 수있는 유일한 링크였습니다. 그것은 유익하고 유용한 링크입니다.

— Roboprog

package-info.java를 사용하면 {@link} 및 기타 독렛을 사용할 수 있습니다. java.lang 클래스를 링크 할 때 javadoc이 생성되면 사용중인 jdk와 일치하는 클래스의 온라인 javadoc을 가리키는 {@link}가 자동으로 나타납니다. ide는 리팩토링 리팩토링을 할 때 잘못된 링크를 찾는 데 도움이 될 수 있습니다.

— Luigi R. Viggiano