현실을 직시하자 : 기본 Javadoc이보기 흉해 보이기 위해 디자이너가 될 필요는 없습니다 .
웹에는 스타일이 변경된 Javadoc을 제공하는 몇 가지 리소스가 있습니다. 그러나 기본 동작은 제품을 나타내며 합리적으로보기 좋을 것입니다.
또 다른 문제는 Javadoc의 유용성이 다른 유사한 리소스에 비해 최신이 아니라는 사실입니다.
특히 거대한 프로젝트는 Firefox의 빠른 검색을 사용하여 탐색하기가 어렵습니다.
실용적인 질문 :
브라우저보다 더 유용한 방식으로 기존 Javadoc을 탐색 할 수있는 독립형 (데스크톱) 애플리케이션이 있습니까?
Mono의 문서 브라우저와 같은 것을 생각하고 있습니다.
이론적 질문 :
Javadoc을 어떻게 든 표준화 된 방식으로 발전시킬 계획이 있는지 아는 사람이 있습니까?
편집 : 이 주제에 대한 Sun의 위키에 대한 유용한 링크 .
답변:
Markdown 형식의 텍스트로 소스 주석을 가져와 동일한 HTML Javadoc을 만드는 Markdown (java) Doclet 을 만들었습니다 .
새로운 doclet은 또한 텍스트에 일부 스타일을 변경하지만 생성 된 HTML은이 단계에서 변경되지 않습니다.
이는 현재 Javadoc의 가장 큰 사용성 문제인 HTML-in-java-commenting 문제를 해결하는 방법입니다.
Javadoc의 개념이 구식이라고 생각하지 않습니다. 내가 볼 수있는 한, 이러한 개념은 수년 전 doxygen이라는 제품에 뿌리를두고 있으며 다른 언어 (예 : 많이 사용되는 Objective-C)에서도 여전히 사용할 수 있습니다. 이것조차도 전임자가 있습니다. Donald Knuth가 TeX ( Literate programming ) 를 만들기 위해 사용한 프로그래밍 환경을 살펴보십시오 .
그럼에도 불구하고 프로그램 코드와 문서를위한 단일 소스를 갖는 것은 흥미로운 아이디어입니다.
그 외에도 JavaDoc 도구에서 지원하는 플러그인 시스템을 사용하여 문서 프레젠테이션을 특별한 요구 사항에 맞게 사용자 정의 할 수 있습니다. 웹을 통해 직접 액세스 할 수있는 데이터베이스에 직접 게시하는 플러그인을 제공 할 수 있습니다. 공동 작업을 사용하면 누구나 원본 소스로 돌아갈 수있는 문서에 대한 추가 설명이나 설명을 제공 할 수 있습니다.
Javadoc은 내가 본 최고의 소스 코드 자동 문서 생성 시스템입니다. 그것의 큰 부분은 그것이 너무 간단하다는 것입니다-원한다면 5 년 된 휴대폰으로도 자바 문서를 검색 할 수 있습니다! 약간의 안면 성형이 필요할 수 있고 특히 JDK는 탐색하기가 힘들다는 데 동의하지만 현재 우리가 가지고있는 것이 작동하는 목적을 위해 RESTful하고 사용하기 쉬운 솔루션이기 때문에 휠을 완전히 재창조하지는 않을 것입니다. 거의 어디서나.
http://download.oracle.com/javase/6/docs/api/java/lang/String.html#String(byte[]):)는 허용되지 않는 괄호, 대괄호 및 기타 문자를 사용하기 때문에 유효하지 않다는 문제가 있습니다. 이로 인해 일부 브라우저에서 중단됩니다.
최근에 Sun이 Javadoc HTML 출력을 현대화하는 작업을하고 있다는 메일을 받았습니다. 해당 메일에서 :
JDK7 용 javadoc / doclet에 대한 개선을 제안합니다. 프로젝트 위키 페이지는 http://wikis.sun.com/display/Javadoc/Home에 있습니다. 제안 된 개선 사항의 일부로 javadoc 출력의 UI가 개선됩니다. 새 디자인 스크린 샷이 프로젝트 위키에 업로드됩니다. javadoc 출력 마크 업은 유효한 HTML 및 WCAG 2.0 규격으로 수정됩니다.
따라서 다소 늦더라도 여전히 작업이 진행되고 있습니다. 그러나 내 눈에 Javadoc의 가장 큰 단점 중 하나는 HTML과의 밀접한 결합입니다. 많은 클래스에는 리터럴 HTML을 포함하고 HTML 인 출력에 의존하는 Javadoc이 있습니다. 안타깝지만 이건 언제든 변하지 않을 것 같아요. 그래도 이는 개발자가 HTML에 원하는 내용을 자유롭게 포함 할 수 있음을 의미합니다. HTML에 유효하지 않거나 형식이 잘못되었을 수도 있습니다. 따라서 javadoc 도구의 출력을 조정하는 것은이 작업의 한 부분 일 뿐이고 다른 부분은 그럴 것입니다. ' t는 변할 수없고 따라서 남아 있습니다.
문서 검색에 관해서는 HTML 문서가 약간 다루기 어렵다는 것을 알았습니다. 저는 보통 Eclipse에서 Javadoc보기를 사용합니다. 단점도 있지만 (느리고 검색 할 수 없습니다) 대부분의 경우 Good Enough ™입니다.
개인적으로 여전히 Javadoc이 매우 유용하다고 생각합니다. 특히 표준화되어 있기 때문입니다. 탐색하기 쉬운 주요 문서 스타일을 알지 못합니다 (매우 주관적 일 수 있지만 개인적으로 MSDN을 사용하는 것이 끔찍하다고 생각합니다).
검색을 위해 : Javadoc 검색 프레임을 사용하면 모든 종류의 Javadoc을 훨씬 쉽게 사용할 수 있습니다. Firefox 용 Userscript 및 Google Chrome 확장 프로그램 으로 사용할 수 있습니다 .
덜 공격적이고 위압적 인 방식으로 표현할 수 있습니다. 대부분의 사람들은 기술 리소스가 어떻게 생겼는지 신경 쓰지 않습니다. "웹 2.0만으로는 충분하지 않습니다!" 멍청한 marketroidspeak처럼 들립니다.
그리고 정확히 무엇을 "더 유용"하다고 생각하십니까? 개인적으로, 나는 확실히 전체 텍스트 검색과 더 나은 사용 브라우저를 원하며 AJAX는 아마도 그것들을 도울 수있을 것입니다.
음, JavaDoc의 좋은 점은 구식과 반대라는 점입니다. 임의로 확장 할 수 있습니다. 계속해서 doclet을 작성하지 않겠습니까?원하는 종류의 API 문서를 생성 을 습니까?
지금까지 아무도 그렇게하지 않은 이유는 (분명히 사실임) 누구의 추측 일 수 있습니다. 아마도 다른 사람은 당신만큼 그것에 대해 강하게 느끼지 않을 것입니다.
저는 개인적으로 HTML (따라서 태그를 다룰 수있는) JavaDoc보다 더 읽기 쉬운 "주석 문서"표준을 원합니다.
예를 들어, 여기에 사용 된 MarkDown은 소스에서 사람이 읽을 수 있고 소스 외부에서 멋지게 형식화되어 훌륭하고 읽을 수 있습니다.
현재 JavaDoc을 사용하면 많은 사람들이 JavaDoc 주석을 사용한다고 생각하지만 실제로 문서화 할 수있는 정도까지 문서화하지는 않습니다. 나는 모든 사람들이 문서화되지 않았거나 거의 문서화되지 않은 API의 온라인 JavaDoc을 탐색했으며 지금까지 사용해야하는 것보다 훨씬 더 사용하기 어렵다고 확신합니다.
이것은 JavaDoc 주석 (예 : 항목 목록)에 넣은 읽을 수있는 구조를 하나의 큰 텍스트 덩어리로 완전히 파괴하는 코드 재구성 기 (예 : Eclipse 내에서 또는 소스 커밋시)에 의해 도움이되지 않습니다. 말 그대로 두 개의 캐리지 리턴을 사용하지 않는 한).
Javadoc을 어떻게 든 표준화 된 방식으로 발전시킬 계획이 있다면 아는 사람이 있습니까?
Javadoc의 향상된 기능을 지정하는 해당 JSR (JSR 260)은 현재 JDK 7에서 제외되었습니다. 계획된 내용에 대한 개요 ( 이 사이트에서 ) :
Javadoc 문서를보다 체계적으로 표시 할 수 있도록보다 풍부한 태그 세트를 제공하려면 Javadoc을 업그레이드하십시오. 이 JSR은 다음을 다룹니다. 메소드 및 필드의 범주화, 클래스 및 패키지의 의미 인덱스, 정적, 팩토리, 일반 메소드에서 사용되지 않는 메소드의 구별, 속성 접근 자 구별, 정보를 뷰로 결합 및 분할, 예제 및 일반적인 사용 사례 포함, 그리고 더.
JDK 7에 대한 전반적인 전망은 매우 암울 합니다.
JavaDoc은 그 자체로 매우 유연합니다. 표준 doclet을 사용자 정의 doclet으로 대체하여 프로젝트 특정 요구를 충족하는 것을 제공 할 수 있기 때문입니다.
내가 작업해온 프로젝트에서 우리는 JavaDoc이 완전히 통합 된 제품을위한 HTML / XML 기반 문서 시스템 (JS에서 클라이언트 측 XSLT 2.0 사용)을 만들었습니다. 이를 위해 XML로 JavaDoc 데이터를 생성하는 데 사용자 정의 doclet이 사용되었으며, 이것은 코드 주석 내에서 HTML 마크 업도 잘 형성되도록하기 위해 tagsoup을 사용했습니다.
이를 통해 단일 페이지 앱 (데스크톱 도구와 유사)을 사용하여 대화 형 사용자 경험을 제공 할 수 있었지만 서버 측 코드 / 인프라없이 모두 브라우저 내에서 가능했습니다. 뷰어에는 검색, 트리 탐색 등과 같은 표준 기능이 포함되었습니다.
다음은 다소 방대한 문서의 샘플 진입 점에 대한 링크입니다. JavaDoc 뷰어 샘플
다음 이미지도 있습니다.
검색 가능한 스마트 한 javadoc 뷰어 :
여러 번 JavaDoc을 검색하는 문제에 직면했습니다. Adnroid 문서 검색 옵션과 같은 것을 찾고있었습니다. 마침내 나는 그런 것을 얻습니다. 파이어 폭스를 사용하는 경우 해결책이 있습니다.
플러그인 GreaseMonkey를 설치하십시오. 우리가 보는 방식대로 웹 페이지를 사용자 정의합니다. (클래스 이름을 검색 할 수 있도록 Java 문서 페이지를 사용자 정의해야합니다.) https://addons.mozilla.org/en-US/firefox/addon/greasemonkey/
greasemonkey가 작동하려면 사용자 정의를위한 사용자 스크립트가 필요합니다. greasemonkey에서 자동으로 다운로드 할 수 있습니다. JavaDoc 검색 프레임 또는 JavaDoc 증분 검색 에서 사용자 스크립트를 설치합니다 .
이것은 나를 위해 잘 작동합니다.