Perl 코드를 문서화하는 가장 좋은 방법은 무엇입니까?

Question

내 제안 코드는 어떻게 문서화 할 수 있습니까? 무엇을 사용하고 어떤 도구가 도움이됩니까?

pod를 html로 변환하는 데 사용하는 모듈은 무엇입니까?

Answer 1

거의 모든 Perl 모듈을 살펴보면 Plain Old Documentation (POD) 형식이 표시됩니다. CPAN Search에서 모듈을 볼 때 원시 소스를 볼 수있는 옵션이 있으므로 원시 포드를 볼 수있는 한 가지 방법이 있지만 명령 행에서 perldoc을 사용할 수도 있습니다.

perldoc -l Foo::Bar 

을 한 번 : 당신은 당신이 그것을 찾기 위해 -l 스위치를 사용하여, 당신의 마음에 드는 편집기에서 볼 수 있도록 파일을 찾을하려는 경우 -m 스위치는 당신에게 파일

perldoc -m Foo::Bar 

를 표시하거나 당신은 당신의 프로그램을 문서화하기 시작한다. 당신은 코드와 함께 코드 안에 파일을 넣을 수있다. 문서가 관련 부분들 옆에 놓이게된다. 또는 시작, 중간 또는 끝 부분이 하나의 큰 덩어리로된다.

포드는 Perl과 함께 제공되는 번역기 (pod2latex, pod2ps, pod2html)를 사용하여 LaTeX, Postscript, HTML 등의 여러 다른 형식으로 쉽게 변환 할 수 있습니다. InDesign으로 이동하는 pod 번역기도 있습니다. Pod::Simple으로 자신 만의 Pod 번역기를 작성하기가 쉽기 때문에 가장 좋아하는 최종 양식으로 번역자를 찾지 못하면 직접 작성하십시오.

포드를 확인하기 위해 테스트 스위트에 추가 할 수있는 몇 가지 도구가 있습니다.모듈은 형식 오류를 확인하고 Test::Pod::Coverage 모듈은 각 서브 루틴을 문서화했는지 확인합니다. 내 Perl documentation documentation에도 관심이있을 수 있습니다.

Answer 2

Perl pod.

Mozilla가 Perl을 문서화하는 방법입니다.

Answer 3

지나치게 뒤집 히면 안되지만 다른 언어로 된 코드를 문서화하는 것과 같은 방법으로 Perl 코드를 문서화하는 가장 좋은 방법입니다.

는 특정 도구에 관해서는, 나는 더 자유 할 필요가 문서에 대한 최종 대체 등 사람 유사한 형식이 적절한 문서, 텍의 큰 덩어리 표준 인라인 주석, 포드의 혼합을 사용합니다. (그리고 다른 언어와 마찬가지로 "Perl 이외의 코드도 문서화하기 위해 포드를 사용합니다.)

Answer 4

나는 확실히 POD을 권장합니다.

POD는 코드와 함께 사용할 수도 있지만 __END__ 이후에 프로그램 맨 아래에 두는 것을 선호합니다 (Damian Conway에서 권장 한 Perl Best Practices).

모든 POD에 웹 프런트 엔드를 제공하는 POD::Server & POD::Webserver을 확인하십시오.

Answer 5

어떤 모듈을 사용하여 을 html로 변환 하시겠습니까?

체크 아웃 Pod::ProjectDocs - 당신은 당신이 search.cpan.org에 표시되는 내용과 같이 HTML 페이지의 집합으로 펄 프로젝트의 모든 POD를 변환하는 간단한 명령 줄 유틸리티를 얻을.

Answer 6

또한 Damian Conway가 Perl Best Practices을 확인하고 싶을 수도 있습니다. 내가 상속 한 작은 Perl 코드 기반을 정리하기위한 팁을 사용했습니다.

Answer 7

아무도 언급하지 않았습니다. Smart::Comments? 언제나 원하는 것은 아니지만 의견에 더 많은 힘이 필요하면 좋습니다.

Answer 8

별도의 사용자 문서 및 코더 문서. 어쩌면 사용자 문서 (tuts, faq, reference)를 거기의 디렉토리 (/ doc)에두고 코더는 코드와 동일하게 넣습니다. 불행하게도 관습에 의해 예상되는, 모듈 자체에 대한 개요를 가지고 있습니다. 이것은 이미 레이아웃 된 것처럼 끝 뒤에 POD 할 수 있습니다. 당신은 코멘트에 넣을 수 있습니다. 코딩 스타일이나 추가 방법은 코드베이스 (루트 디렉토리)에 별도의 .pod 파일을 넣는 방법으로 제공합니다.