YARD를 사용하여 간단한 스크립트를 문서화하는 방법은 무엇입니까?

Question

내 코드를 문서화하는 데 관심이 있습니다. 대다수는 내가 이 아닌 새 클래스를 만드는 스크립트입니다.

YARD 문서를 읽고 YARD 설명서를 실제로 구현하려고하면 정의 된 클래스 내에서 YARD 태그를 선언 한 것으로 보입니다. 아래 예제 코드에서와 같이 클래스를 만들거나 클래스에 새 메서드를 추가 할 때 YARD를 성공적으로 사용했으며 @author 및 @example과 같은 YARD 태그를 사용하여 간단한 것들을 문서화 할 수있었습니다.

#!/usr/bin/env ruby -wKU 

## a YARD test 

class String 

    # Prints a string using two supplied strings 
    # 
    # @param str1 [String] A string to print 
    # @param str2 [String] A string to print 
    # @return [String] A printed string 
    def yardTest(str1, str2) 
    p sprintf("Hello, %s, %s", str1, str2) 
    end 

end 

내 질문 은 다음과 같습니다

1. 클래스를 정의하지 않고 코드 (특히 방법)을 문서화하는 YARD 태그를 사용하는 방법이 있나요?
2. 그렇지 않은 경우 내 코드에 광범위한 주석을 넣는 것 이외의 다른 솔루션이 있습니까?

Answer 1

클래스 또는 모듈 기반 메소드와 마찬가지로 스크립트의 메소드를 문서화하십시오. 야드는 그들을 "최상위 이름 공간"의 일부로 문서화해야합니다.

#!/usr/bin/env ruby -wKU 

# Prints a string using two supplied strings 
# 
# @param str1 [String] A string to print 
# @param str2 [String] A string to print 
# @return [String] A printed string 
def yardTest(str1, str2) 
    p sprintf("Hello, %s, %s", str1, str2) 
end 

당신은 또한 다른 목적을 위해 자사의 사용자 스크립트의 API를 문서화하는 것이 좋습니다하고 있습니다

스크립트에 다음 수정 단지 class String 래퍼를 제거 작동 물론 관객.

또한 작업을 수행하는 메서드에서 명령 줄 인터페이스를 분리하는 것을 고려하십시오.이 경우 적절한 모듈과 클래스가 만들어지게됩니다. 이는 원격으로 복잡한 작업을 수행 할 때 자연스러운 패턴이며 향후에 스크립트간에 또는 명령 줄에서 호출되지 않는 것에 대한 논리를 공유 할 수있게 해줍니다. thor gem을 살펴볼 수 있습니다. 이것은 명령 줄 스크립트를 작성하기위한 프레임 워크이며, 멋진 추상화 패턴을 따르는 명령 줄 인터페이스의 예를 포함합니다. Thor는 표준 연습 사용법과 도움말을 명령 줄 스크립트에 쉽게 포함시킬 수 있습니다.