POD보다 펄 코드를 문서화하는 더 좋은 방법은 없습니까?

Question

필자는 오랫동안 Perl 프로그래머이지만 POD의 문서에는 항상 문제가 있습니다.

코드에 POD 주석을 사용하면 코드를 읽기가 어렵습니다. 파일 끝에 POD 주석을 사용하면 문서가 코드와 동기화되지 않을 위험이 있습니다.

Java와 비슷한 문서 스타일이 누락되었습니다.

/** 
* @description 
* ... 
*/ 

더 쉽고 직관적 인 문서 스타일을 찾습니다. 그런 것이 있습니까?

Answer 1

빠른 검색 결과 Doxygen (매우 Javadoc에 가깝습니다)을 사용하여 Perl 코드를 문서화 할 수 있습니다.

Answer 2

글쎄, POD는 Perl 문서를 게시하기 위해 허용되는 표준입니다.

나는 그것을 유지하는 것이 다소 짜증이납니다. 나는 최근에 설명서를 유지하고 릴리스시 포드에 빌드하기 위해 Pod::Weaver을 사용하여 실험했습니다. 약간의 까다로운 점은 POD를 필터링하고 빌드하는 방법이 매우 융통성이 있으며 (POD 또는 기타의 경우) 좀 더 자세한 문서화 작업을 수행 할 수 있다는 것입니다. 그러나 유망한 것으로 보인다. 그보다 더 많은 판단을 내리기에는 아직 너무 이르지만, 유망한 것으로 보인다.

희망이

Answer 3

은 왜 코드가 포드와 읽기 어렵다 생각하는 데 도움이? 코드가 다른 코드로 읽히기가 어렵습니까? 아마도 작은 메소드를 작성하는 대신 코드의 특정 부분에 너무 많은 것을 넣을 것입니다. 코드를 읽기가 어렵지 않을까요?

코드 끝에 모든 문서를 넣을 필요는 없습니다. Pod는 서브 루틴이나 메소드 바로 옆에 서브 루틴이나 메소드에 대한 문서를 넣을 수 있도록 코드와 완벽하게 잘 맞습니다.

포드와 관련하여 다른 문제가 있습니까?

Answer 4

POD에 문제가있는 경우는 정확하게 강조 표시하지 않는 텍스트 편집기를 사용할 때입니다.

/** 
* Returns an Image object that can then be painted on the screen. 
* The url argument must specify an absolute 

{@link URL}. The name 
* argument is a specifier that is relative to the url argument. 
* <p> 
* This method always returns immediately, whether or not the 
* image exists. When this applet attempts to draw the image on 
* the screen, the data will be loaded. The graphics primitives 
* that draw the image will incrementally paint on the screen. 
* 
* 

@param url an absolute URL giving the base location of the image 
* 

@param name the location of the image, relative to the url argument 
* 

@return  the image at the specified URL 
* 

@see   Image 
*/ 
public Image getImage(URL url, String name) { 
     try { 
      return getImage(new URL(url, name)); 
     } catch (MalformedURLException e) { 
      return null; 
     } 
} 

에 해당하는 펄에 비해 :

그냥 자바 this에 지나치게 자세한 보인다 모든 것을 좋아한다.

=item getImage(url, name) 

This method always returns immediately, whether or not the 
image exists. When this applet attempts to draw the image on 
the screen, the data will be loaded. The graphics primitives 
that draw the image will incrementally paint on the screen. 

url must be an absolute URL giving the base location of the image 

name is the location of the image, relative to the url argument 

=cut 

sub getImage{ 
    my ($url,$name) = @_; 

    ... 
} 

Answer 5

Rinci을 살펴볼 수 있습니다. 이것을 사용하는 응용 프로그램의 예 : File::RsyBak, Git::Bunch, App::OrgUtils.

다음은 모듈을 문서화하는 방법입니다. 모듈에 % SPEC을 선언하고 그 안에 문서를 넣습니다. 각 함수는 자체 키를 가져옵니다. 미리 정의 된 필드가 있습니다. 현지화가 지원됩니다. 서식 지정은 Markdown에서 수행됩니다. 예 : 대신 자바 - 또는 Perl "의견"에 문서를 넣고 5 스타일을 사용

$SPEC{':package'} = { 
    summary => 'Module to do foo', 
    "summary.alt.lang.id_ID" => "Modul untuk melakukan foo", 
    description => <<EOT, 
Blah... 
... 
EOT 
    links => [...], 
}; 
$SPEC{func1} = { 
    summary => '...', 
    description => '...', 
    args => { 
     arg1 => { 
      schema => ..., 
      summary => ...., 
      description => ..., 
     }, 
    }, 
    examples => [...], 
    links => [...], 
    ... 
}; 

, 그것은 프로그램에 직접 사용할 수있는 데이터 구조를 사용합니다.(Perl 6도 이런 식으로 진행됩니다.) 파이썬 docstring이 미친 (또는 구조화 된) 것으로 생각하십시오.

메타 데이터 (사양)에서 POD, 텍스트, HTML을 생성하는 도구가 있습니다. 문서 외에도 메타 데이터는 인수 유효성 검사, 명령 줄 인터페이스 등과 같은 다른 유용한 정보에도 유용합니다.

공개 : 저는 개발자입니다.

Answer 6

나 자신, 나는 종종 문서에 코드 항목을 재현하고자합니다. 그러나 파싱하는 동안 코드를 읽도록 POD를 속일 수는 있지만 코드를 파싱하는 동안 코드를 실행하게하는 방법을 찾으십시오. 나는 정말이 정착해야하나요 :

=head1 Variables 

use vars (%V &C) 

=cut 

use vars (%V %C) 

=head2 Constants 

$C{hashConstant1} = "/path/to/file" 

=cut 

$C{hashConstant1} = "/path/to/file"; 

=head2 Variables 

$V{strVar1} = undef 

=cut 

$V{strVar1} = undef; 

그럼 다시, 대부분의 언어가 문서로 이중 입력을 필요로한다.