YARD를 사용하여 최상위 네임 스페이스의 메서드를 문서화

Question

YARD를 사용하여 Ruby 코드를 문서화하고 야드를 가져 오는 데 문제가 있습니다 설명서 야드롬의yardoc의 HTML 출력에 표시 할 최상위 네임 스페이스의 일부 메서드에 대한 설명서를 만들었습니다.

내 설명서는 @api 태그가 추가 된 lib/yard/globals.rb의 YARD 보석과 본질적으로 동일합니다. 제거하려고 시도했으나 --api 매개 변수없이 yardoc을 실행했지만 문제가 해결되지 않았습니다.

#!/usr/bin/ruby 

# @group PIP Negotiation: Backend and helper methods 
# 
# Deserializes a topology graph in YAML format into the database. 
# 
# @api pip-negotiate 
# @param [String] graph A FleRD graph in YAML format 
# @return [Boolean] status True if graph was deserialized successfully, False otherwise. 
# @return [Integer] gl_id The database ID of the deserialized GraphLabel (nil if deserialization failed). 
# @return [Array] output Standard output channel of flerd-deserialize.rb(1) 
# @return [Array] output Standard error channel of flerd-deserialize.rb(1) 

def insert_graph(graph) 
    return [ true, 1, ["1"], [""] ] # Not the actual method body. 
end 

# @endgroup 

나는 HTML 문서 모두를 생성하는 yardoc를 실행 처음 잘 보이는 :

이

은 예입니다

% yardoc -o pip-negotiate --api pip-negotiate '**/*.rb'     
Files:   1 
Modules:   0 ( 0 undocumented) 
Classes:   0 ( 0 undocumented) 
Constants:  0 ( 0 undocumented) 
Methods:   1 ( 0 undocumented) 
100.00% documented 
% 

html로 비록 내 문서 중 하나를 포함하지 않는 생성 . 모두 에 포함되어 있으며 pip-negotiate API 태그가 포함 된 메소드 목록이 있습니다. 여기 자신을 볼 수 있습니다 내가 대신 기대했던

http://btw23.de/tmp/pip-negotiate/api/method_list.html

더 최상위 방법에 대한 YARD 자신의 문서와 같은 것이었다 :

http://rubydoc.info/gems/yard/toplevel

아마도 특별한 마법이 있습니까 내 yardoc 호출에 누락되었습니다.

내 yardoc 루비 버전 1.8.7에서 실행 0.8.6.2이다 (2012-06-29 패치 레벨 370) x86_64에-리눅스]

Answer 1

정확한 구문은 표시 될 :

yardoc -o pip-negotiate --api=pip-negotiate '**/*.rb' 

--api 옵션이 올바르게 작동하려면 등호가 필요합니다. 나는 그렇지 않으면 pip-negotiate이라는 이름이 입력 파일 이름으로 사용되어 문서를 파싱했다는 것을 의심합니다.

Answer 2

--api의 존재 여부는 차이가없는 것처럼 보입니다. 등호 기호가있는 경우 --api 옵션을 사용하면 메서드가 표시되지 않습니다. 등호에 관계없이 다른 경우에도 작동합니다. 나는 최상위 네임 스페이스에없는 인스턴스 메서드 모음에 문서를 분류하는 데 많이 사용 해왔다. 나는 지금 이유를 발견했다고 생각합니다.

분명히 @api 태그는 다소 네임 스페이스에 민감하며 특유의 방식입니다.

% yardoc -o pip-negotiate --api=pip-negotiate '**/*.rb' 
% yardoc -o pip-negotiate --api pip-negotiate '**/*.rb' 

을하지만 우리는 방법에 이르기까지 @api 태그를 이동하는 경우가 중단됩니다 : 그것은 insert_graph() 미세의 방법 설명서를 렌더링이 두 yardoc 호출 중 하나와

#!/usr/bin/ruby 

# @api pip-negotiate 

class Foo 

# Deserializes a topology graph in YAML format into the database. 
# 
# @param [String] graph A FleRD graph in YAML format 
# @return [Boolean] status True if graph was deserialized successfully, False otherwise. 
# @return [Integer] gl_id The database of the deserialized GraphLabel (nil if deserialization failed). 
# @return [Array] output Standard output of flerd-deserialize.rb(1) 

def insert_graph(graph) 
    return true, 1, ["1"], [""] # Not the actual method body. 
end 

end 

:이 예제를 고려 사물 :

#!/usr/bin/ruby 

class Foo 

# Deserializes a topology graph in YAML format into the database. 
# 
# @param [String] graph A FleRD graph in YAML format 
# @return [Boolean] status True if graph was deserialized successfully, False otherwise. 
# @return [Integer] gl_id The database of the deserialized GraphLabel (nil if deserialization failed). 
# @return [Array] output Standard output of flerd-deserialize.rb(1) 
# @api pip-negotiate 

def insert_graph(graph) 
    return true, 1, ["1"], [""] # Not the actual method body. 
end 

end 

yardoc 호출과 관계없이 thod 설명서는 무시되지만 메서드가 나열됩니다. 내 가설은 여분의 사이클을 YARD의 소스에서 확인하지 않기 때문에 가장 바깥에있는 taggable 네임 스페이스의 @api 태그 (이 예에서는 Foo 클래스 )의 깨지지 않은 체인이 있어야한다는 것입니다. 그리고 지금까지 최상위 네임 스페이스에 태그를 붙이는 방법을 찾지 못했습니다. 그래도 도움이 될 것입니다. 말했다되고 그건

, --api 파괴 것들에 대한 의견 오른쪽 궤도에 저를 얻었다 : 나는 --api 매개 변수를 생략하면 메소드 문서는 아직 방법 목록에 표시되지 않지만, 그것은에 표시 않는다 모든 장소의 클래스 목록 ('최상위 이름 공간'아래) 그래서 매개 변수를 생략하려고 시도한 것은 처음입니다.

I가 표시되는 방법 목록을 유지하기 위해 YARD 포맷터 작업을 시도 할 것이다, 그래서 저를 혼동대로 내 사용자를 혼동하지 않고,/내 문서를 구분해서 그러한 내 코드를 리팩토링 시도 주어진 파일에 에 복수 @api 태그가 필요하지 않습니다.