야후 사용자 인터페이스 블로그 (YUIBlog)

YUI 닥에 대한 카를로 Zottmann의 데이나 테마

제가 사용하려는 YUI 의사를 내 자바 스크립트 문서화 요구 사항 모두를 위해. 그냥 때문이 아니라 - 그냥 일반 바닐라 JS이나 jQuery 코드를 문서화를 위해 잘 작동하는 것으로 나타났습니다 YUI 기반의 프로젝트.

처음에는 내가 더 쓰는 경향으로 내가 의심 스러웠 jQuery YUI 코드가보다. 그것은 YUI 닥 쉽게 내 작업 흐름에 통합되는 찾을 수있는 즐거운 놀라움이었고, 내 아닌 YUI 프로젝트에 대한 유용한 설명서를 생산할 수 있습니다. 물론, 그것은 프로젝트의 파일 구조 등에 관한 몇 가지 기대를 가지고 있지만, 이러한 기대에 아무도 나를 위해 showstoppers 없습니다. 반면에 그것은 빛이 시스템입니다, 나는 그것을 즉시 실행하실 수 있습니다.

도구가 내 소스 코드를 구문 분석하고 자동 나를 위해 품질 문서를​​ 작성하는 것이 좋은가 -뿐만 아니라 빠르게 등등 나중에 함수 호출을 찾는 동안, 제가 보기엔 두 가지 방법으로 값을 추가합니다 :

첫째, 난 내 자신을 위해서 제 코드는 어느 쪽이든 문서화 - 아마 몇 달 안에 다시 방문하고 제가 빨리 데리러 수 있어야 겠어. 설명서가 발생하지 않는 것은 내 고객을주고 싶다 노출이 아닌 미래에 어떤 혼란을 의미합니다.

둘째, 코드 설명서 클라이언트에 대한 추상적인 개념을 보시면 : 나는 그것이있다,하지만 난 "증명"할 수있는 유일한 방법은 내 주장이 편집장을 해고하는 것입니다 그녀에게 내의 주석 블록에서 손가락을 가리킬 수 있습니다 코드입니다. 그렇다면 정말 매우 인상적 보이지 않는군요 - 최악에서 그들은 "적절한"문서에 대한 유감 변명 같아.

그러나 내 브라우저를 해고 YUI 사이먼에 의해 처리하고 처리된 아주 동일한 코멘트 보여주는 - 그 사람, 바로 거기 monkeying 전문적인 코드하네요 - 깨끗하고 반짝 이는, 일관된합니다.

(방금 "위키 문서에서 코드는과 똑같고 번거로움을 덜는"생각하면 내 슬픈 골프 박수를 받아주십시오 - 그게 아니거든요.)

불행히도, 난 기지 YUI 닥 피부의 팬이 아니야. 나는 내 클라이언트 코드의 solidly 문서화 조각 이상 손으로, 나는 그들이 solidly 문서화 코드를보고 싶은 경우, 나에게, YUI 닥의 기본 테마는 밝게 빛날 충분하지 않습니다.

내가 어떤을 찾을 수 없습니다 교체 테마 주위에 찾고. - 그래서 몇 주 전에 제가 직접 쓰기로했다 다나를 . 다음 예제 스크린샷입니다 :

당신이 위에서 볼 수 있듯이, 나는 예제로 잘 알려진 YUI API 문서를 생성했습니다. 여기에요 원래 YUI 설명서 - 여기 새로운 스포츠 아주 똑같은 자료입니다 데이 테마 .

나는 눈에 더 후자에 들지 - 당신이 동의 바랍니다! 비트 주위를 누르고 필터와 놀아, 비교 심층 더 클래스 documentations의 일부를 확인, 럭셔 리한 아직 싼 플라스틱 아래를 느낍니다.

지금까지, 나는 긍정적인 피드백을 많이 나왔던 거예요. 나의 클라이언트는 청소기 모습에 감사 드리며, 제가 생성된 마크업 바로 아래, 내 프로젝트에 넣어 작품의보다 전문적인 프레 젠 테이션에 대해 더 잘 느낍니다.

그것이 만들어진 방법

나는 기본적 YUI 닥 템플릿 내에 HTML의 모든 비트를 날려 YUI 닥의 핵심 블록의 상단에 흠집 layering 내 자신의 마크업부터 다시 시작하여 데이를 끊었 치타 코드입니다. (치타는 YUI 닥에서 사용하는 파이썬 템플릿 지정 엔진입니다. # 당신이 템플릿에서 찾을 블록 치타에 의해 실행 파이썬 코드를 포함.)

솔직히 말해서하면, 템플릿에 일어나는 것 자체가 정말 공원을 산책 아니었다 - YUI 박사님의 템플릿 주석이 아닌, 시스템으로 초보자로서 지향 점점 것은 좀 시간이 걸렸습니다. 내가 구조와 치타 논리를 이해 느낌을 받았을 때, 몇 가지 정말로 간단한 구조로 교체, 마크업의 나머지 들어냈네, 그 위에 구축. 그것은 시간이 좀 걸렸어요.

자신의 테마를 작성할 생각한다면, 나는 데이나 사용하거나 추천할 main.tmpl 출발점으로, 또는보고 올바른 형식의 원본 main.tmpl . 많은 보단 당신에게이 템플릿을 가지고 죽었습니다.

나는 디자이너가 아니에요, 저는 많은 종과 경적을 추가하지 않고 모양이 간단하고 명확하게하기 위해 노력했습니다.

내장 근사한

나는 객체 유형 매개 변수 (IMHO) 더 나은 화면을 구현의 자유를 구속 수사 : 여러 개의 매개 변수가 하나의 개체에 대한 속성으로 전달하는 경우 해당 개체는 테이블의 첫 번째 열에 매개 변수로 표시됩니다.

예를 들어,, 당신도 세 속성을 포함하는 객체 유형 매개 변수를 기다리는 방법을 문서화하는 말 :

 * @param obj.param1 {String} A string! * @param obj.param2 {Number} A number! * @param obj.param3 {Boolean} A boolean, surprisingly! 

다음은이 방법은 생성된 문서에 표시됩니다 방법은 다음과 같습니다

기본 테마 : method( obj.param1, obj.param2, obj.param3 )
데이나 주제 : method( obj )

실제 예를 들어, 문서를 볼 YAHOO.widget.DataTable의 이벤트 .

이 치료는 출력이보다 간결하게 것을 알게됩니다.

요구 사항

데이 나의 하나가 필요 하기 YUI 닥 빌드를 , 예를 들어, 잘 50 작품을 빌드 -하지만 YUI 닥 1.0.0b1 작동하지 않습니다.

설치 / 사용법

당신이 YUI 박사 일어나서이 시점에서 실행했습니다 가정합니다. 그냥 다운로드 GitHub에서 다나가 , 짐을 풀어 그것을 말해요 yuidoc.py 통해 그것을 사용하는 -t/--template 옵션을 선택합니다.

닫기 발언

다나는 여전히 진행중인 작품입니다; 일부 HTML로 예를 들면 왼쪽으로 몇 가지 사소한 문제가 없습니다 code 너무 폭 나올 블록. 이것은 나를 위해 깨지지 않습니다,하지만 마일리지가 다를 수 있습니다.

나처럼, 내가 (힌트, 힌트)처럼, 체크 아웃 YUI 닥에서 Markdown 지원의 개념에 현기증이 나네, 독자들을 위해 마이크 웨스트의 YUI 닥 포크 정확히 것을 추가합니다. 우리가 새로운 오리지널 YUI 닥 릴리스가 나올 때까지 기다리는 동안, 내 말은. * 기침 ;)이 *

당신은 겁니다 GitHub에 다나를 찾아 . 당신이 그렇게 의향이 있으시다면, 당신은 다운로드받을 수 있습니다 압축 / tgz 파일로 최신 stable 릴리스 도하고. 어떤 오류가 발생하면, 제발 티켓을 만듭니다 .

데이 나 MIT와 GNU GPL v2를 아래 듀얼 허가된 것입니다. 그것은 사파리 5 (OSX), FF3.6 (OSX), Internet Explorer 8 (WinXP)에서 테스트되었습니다있어.

대화 찾기 : bloglines | 테크노

공유하고 확장할 수 : del.icio.us에 북마크 | 디그 그것! | reddit!