방금 레일 애플리케이션을 문서화하기 시작했습니다. 나는 이것이 실제로 rdoc에 의해 수행된다는 것을 알고 있으므로 구문에 관한 rdoc 가이드를 따라 갔지만 모델의 속성, 유효성 검사 및 모델 간의 관계를 설명하려고했을 때 막혔다. 주로 ActiveRecord의 일부이기 때문이다. 레일 애플리케이션을 문서화하는 방법이나 내가 누락 된 부분이 있는지에 대한 가이드 또는 좋은 연습이 있는지 궁금합니다.레일 애플리케이션을 문서화하는 방법은 무엇입니까?
이 모든 것을 클래스 설명에 넣을 수는 있지만, 선언 자체 (has_many, validates_presence_of 등)와 더 밀접하게 연결된 방법이 있는지 궁금하다.
저는 개인적으로 YARD - http://yardoc.org을 선호합니다. 이는 IMHO를 문서화하는 데 더 효과적입니다. 레일스에 대한 특정 처리기가 있는지 모르겠지만 하나를 쓰는 것은 매우 쉽습니다. http://yardoc.org/guides/extending-yard/writing-handlers.html 좋은 예가 야드 보석의 일부일 수 있습니다. lib/yard/handlers/ruby / attribute_handler .rb
시나리오가 읽기 쉬운 오이를 사용하는 경우 특히 테스트가 개발자를위한 설명서의 일부임을 명심하십시오. 방법을 매우 짧게 유지하고 설명이 포함 된 이름의 테스트 메소드가있는 경우. "사용자 이름을 설정해야합니다."일반적으로 메서드에 대한 주석이 필요하지 않습니다.
레일의 유효성 검사 또는 다른 부분 나는 문서화하지 않을 것입니다. Rails 개발자가되는 이유 중 하나는 이러한 작업 방식을 이해하는 것입니다. 코드를 유지 보수하는 다른 관리자가 유효성 검사 또는 Rails에 내장 된 다른 작업을 알 수 있다는 것은 공정한 가정이라고 생각합니다. 동일한 논리에 따라, 프레임 워크의 기능이나 행복한 경로 (많이 변경하지 않은)를 [문서화 된] 제 3 자 코드와 함께 사용할 수 있다면, 많은 문서가 작성 될 것입니다.
나는이 접근 방식을 좋아하지만, 실제로는 잘될 것이라고 생각하는 개발팀이 있지만 실제 문서가 필요하다. 개발자를 위해 엄격하게 사용되지는 않을 것이지만 실제로는 걱정하지 않는 사람이 필요하다. 테스트 (및 할 필요가 없습니다). – ramontiveros
반면에 유효성 검사가 해석하기가 항상 쉬운 것은 아니며, 심지어 필자의 경우에도 필자는 -180과 180 사이의 숫자 특성에 대한 유효성 검사를 일부 실시합니다. 위도 값이며이 값은이 범위에만있을 수 있습니다. 그리고 이것은 단지 쉬운 것입니다. 나는 관계와 제약을 더 추상적으로 포함하는 다른 검증을 가지고 있습니다. 다시 읽었을 때 코드가 처음에는 명확하지 않습니다. – ramontiveros
나는 이것이 매우 흥미로운 접근이라고 생각한다. 나는 유일한 문제는 아직 조금 어려워 보인다는 것과 기대했던 것보다 더 많은 학습 곡선을 가지고 있다고 생각한다. 그럼에도 불구하고 나는 그것이 많은 잠재력을 가지고 있다고 생각한다. 마이 그 레이션의 문서로 데이터베이스를 피드 한 다음 생성기로 문서를 가져 오는 것과 같은 멋진 기능을 상상하기 시작했습니다. 그런 식으로 한 돌로 두 마리, 응용 프로그램 설명서 및 데이터베이스 설명서를 죽일 수 있습니다. – ramontiveros