Javadoc에 대한 훌륭하고 현대적인 대안이 있습니까?
현실을 직시하자 : 기본 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하고 작동하기 쉬운 솔루션이기 때문에 휠을 완전히 재창조하지는 않을 것입니다. 거의 어디서나.
최근에 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 ™입니다.
당신의 실용적인 질문에 답하기 위해 나는 구글을 검색하고 친구들에게 물어 보았고 이것들을 생각해 냈습니다. Forrestdoc, doclet 및 doxygen.
두 번째 질문은 "Web-oh-twoeye"는 아니지만 적어도 오프라인 환경에서 작업 할 수 있으며 API와 함께 제공 할 수있을만큼 작습니다. 나는 프레임 사용을 간과하지만 javadoc에서는 잘 작동합니다. 나는 그것을 바꿀 계획을 보지 못했습니다. Eclipse는 javadoc을 읽고, 해석하고, 생성하는 한 지원합니다.
개인적으로 여전히 Javadoc이 매우 유용하다고 생각합니다. 특히 표준화되어 있기 때문입니다. 탐색하기 쉬운 주요 문서 스타일을 알지 못합니다 (매우 주관적 일 수 있지만 개인적으로 MSDN을 사용하는 것이 끔찍하다고 생각합니다).
검색 : Javadoc 검색 프레임을 사용하면 모든 종류의 Javadoc을 훨씬 쉽게 사용할 수 있습니다. Firefox 용 Userscript 및 Google Chrome 확장 프로그램 으로 사용할 수 있습니다 .
덜 공격적이고 위압적 인 방식으로 표현할 수 있습니다. 대부분의 사람들은 기술 리소스가 어떻게 생겼는지 신경 쓰지 않습니다. "웹 2.0으로는 충분하지 않습니다!" 멍청한 marketroidspeak처럼 들립니다.
그리고 정확히 무엇을 "더 유용"하다고 생각하십니까? 개인적으로, 나는 확실히 전체 텍스트 검색과 더 나은 사용 브라우저를 원하며 AJAX는 아마도 그것들을 도울 수있을 것입니다.
음, JavaDoc의 좋은 점은 구식과 반대라는 점입니다. 임의로 확장 할 수 있습니다. 원하는 종류의 API 문서를 생성 하는 doclet 을 작성하는 것이 어떻습니까?
지금까지 아무도 그렇게하지 않은 이유는 (분명히 사실임) 누구의 추측 일 수 있습니다. 아마도 다른 사람이 당신만큼 그것에 대해 강하게 느끼지 않을 수도 있습니다.
DocBook doclet이 있습니다. DocBook은 (X) HTML보다 풍부한 문서 유형이며 기술 내용을 설명하는 데 더 적합합니다. DocBook 소스에서 모든 종류의 다양한 출력 형식을 생성 할 수 있습니다.
저는 개인적으로 HTML (따라서 태그를 다룰 수있는) JavaDoc보다 더 읽기 쉬운 "주석 문서"표준을 원합니다.
예를 들어 여기에 사용 된 MarkDown은 소스에서 사람이 읽을 수 있고 소스 외부에서 멋지게 형식화되어 훌륭하고 읽을 수 있습니다.
현재 JavaDoc을 사용하면 많은 사람들이 JavaDoc 주석을 사용하지만 실제로 문서화 할 수있는만큼 문서화하지는 않습니다. 나는 모든 사람들이 문서화되지 않았거나 거의 문서화되지 않은 API의 온라인 JavaDoc을 탐색했으며 지금까지 사용해야하는 것보다 훨씬 더 사용하기 어렵다고 확신합니다.
이것은 JavaDoc 주석 (예 : 항목 목록)에 넣은 읽을 수있는 구조를 하나의 큰 텍스트 덩어리로 완전히 파괴하는 코드 재 포매터 (예 : Eclipse 내에서 또는 소스 커밋시)에 의해 도움이되지 않습니다. 말 그대로 두 개의 캐리지 리턴을 사용하지 않는 한).
Javadoc을 어떻게 든 표준화 된 방식으로 발전시킬 계획이 있다면 아는 사람이 있습니까?
Javadoc의 향상된 기능을 지정하는 해당 JSR (JSR 260)은 현재 JDK 7에서 제외되었습니다. 계획된 내용에 대한 개요 ( 이 사이트에서 ) :
Javadoc 문서를보다 체계적으로 표현할 수 있도록보다 풍부한 태그 세트를 제공하려면 Javadoc을 업그레이드하십시오. 이 JSR은 다음을 다룹니다. 메소드 및 필드의 범주화, 클래스 및 패키지의 의미 인덱스, 정적, 팩토리, 일반 메소드에서 사용되지 않는 메소드의 구별, 속성 접근 자 구별, 정보를 뷰로 결합 및 분할, 예제 및 일반적인 사용 사례 포함, 그리고 더.
JDK 7에 대한 전반적인 전망은 매우 암울 합니다.
JavaDoc은 그 자체로 매우 유연합니다. 표준 doclet을 사용자 정의 doclet으로 대체하여 프로젝트 특정 요구를 충족하는 것을 제공 할 수 있기 때문입니다.
On the project I've been working on, we created an HTML/XML-based documentation system (using client-side XSLT 2.0 on JS) for our product with JavaDoc fully integrated. For this, a custom doclet was used to produce JavaDoc data in XML, this used tagsoup to ensure even HTML markup within code comments were well formed.
With this, we were able to deliver an interactive user experience using a single-page app (similar to a desktop tool), but all from within the browser - without any server-side code/infrastructure. The viewer included standard features such as search, tree navigation etc.
Here's a link to a sample entry point in the rather vast documentation: JavaDoc viewer sample
Here's an image also: 
A smart seachable javadoc viewer:
For many times, I face the problem of browsing JavaDoc. I was looking for something just like Adnroid doc search option. At last I get something like that. If you use firefox the solution is here.
Install the plugin GreaseMonkey, its kinda customizing web page the way we see. ( We need to customize any java doc page, so we can search on class name) https://addons.mozilla.org/en-US/firefox/addon/greasemonkey/
For greasemonkey to work, we need some user script for customization. This can be downloaded by greasemonkey automatically. Install the userscript from JavaDoc search frame or JavaDoc incremental search.
This works great for me.
참고URL : https://stackoverflow.com/questions/1026553/are-there-some-good-and-modern-alternatives-to-javadoc
'Programing' 카테고리의 다른 글
| System.Net.WebRequest가 지원하는 SSL / TLS 버전은 무엇입니까? (0) | 2020.10.15 |
|---|---|
| Jetifier는 무엇입니까? (0) | 2020.10.15 |
| Twitter Bootstrap의 Font Awesome vs Glyphicons (0) | 2020.10.15 |
| R에서 정수 클래스와 숫자 클래스의 차이점은 무엇입니까 (0) | 2020.10.15 |
| Java에서 기본 키워드의 목적은 무엇입니까? (0) | 2020.10.15 |