Jakieś sugestie, w jaki sposób mogę udokumentować mój kod Perla? Czego używasz i jakie narzędzia są dostępne, aby mi pomóc?Jaki jest najlepszy sposób udokumentowania kodu Perla?
Z którego modułu korzystasz, aby przekonwertować plik pod html?
Zajrzyj do niemal dowolnego modułu Perla, a zobaczysz format Plain Old Documentation (POD). Na CPAN Search, patrząc na moduł, masz możliwość przeglądania surowego źródła, więc jest to jeden ze sposobów patrzenia na surowy podajnik, ale możesz także użyć perldoc z wiersza poleceń. Przełącznik -m pokazuje plik
perldoc -m Foo::Bar
Albo, jeśli chcesz znaleźć plik, dzięki czemu można patrzeć na to w swoim ulubionym edytorze, należy użyć przełącznika -l go znaleźć:
perldoc -l Foo::Bar
Raz zaczynasz dokumentować swój program, wstawiasz Pod w pliku z kodem, albo przeplata się z kodem, tak że dokumentacja jest obok odpowiednich części, albo na początku, w środku lub końcu jako jedna duża porcja.
Pod można łatwo przetłumaczyć na kilka innych formatów, takich jak LaTeX, Postscript, HTML itd. Z tłumaczami dołączonymi do Perla (pod2latex, pod2ps, pod2html). Mam nawet tłumacza na podsieciach, który trafia do InDesign. Pisanie własnego tłumacza Pod jest łatwe z Pod::Simple, więc jeśli nie znajdziesz tłumacza do swojej ulubionej formy końcowej, po prostu zrób to sam.
Istnieje również kilka narzędzi, które można dodać do zestawu testów w celu sprawdzenia kapsuły. Moduł Test::Pod sprawdza błędy formatowania, moduł Test::Pod::Coverage sprawdza dokumentację każdego podprogramu i tak dalej. Możesz również być zainteresowany moim Perl documentation documentation.
W ten sposób Mozilla dokumentuje swój Perl.
Nie należy przesadzać, ale najlepszym sposobem dokumentowania kodu Perla jest to samo, co dokumentowanie w innym języku.
Jak dla konkretnych narzędzi, używam mieszankę standardowych komentarze inline, Pod większych kawałków dokumentacji gdzie format podobny do człowieka jest właściwe, a TeX jako ostatecznej awaryjnej na dokumenty, które muszą być bardziej freeform. (I, w duchu "tak samo jak w jakimkolwiek innym języku", tak, używam też pod do dokumentowania kodu nie-Perla.)
Zdecydowanie polecam POD.
POD może być również używany w linii z kodem, ale wolę umieścić na dole programu po __END__ (zgodnie z zaleceniami Damiana Conwaya w Perl Best Practices).
Spójrz na POD::Server & POD::Webserver, która zapewnia interfejs WWW dla wszystkich urządzeń POD.
Który moduł chcesz przekonwertować pod na html?
Wyjazd Pod::ProjectDocs - masz proste narzędzie wiersza polecenia, które będzie przekonwertować wszystkie POD w projekcie Perl do zestawu stron HTML, które wyglądają tak samo jak to, co widzisz na search.cpan.org.
Teraz dni w niektórych przypadkach jest hande [Mojolicious :: Plugin :: PODRenderer] (http://mojolicious.org/perldoc/Mojolicious/Plugin/PODRenderer) –
Możesz również chcieć sprawdzić Perl Best Practices Damiana Conwaya. Użyłem kilku wskazówek do oczyszczenia małej odziedziczonej bazy kodu Perla.
Nikt nie wspomniał o Smart::Comments? Nie zawsze jest to, co chcesz, ale dobre, jeśli potrzebujesz więcej mocy do komentarzy.
Ten moduł jest niesamowity. Ku zaskoczeniu, nigdy wcześniej o tym nie słyszałem. Nie mogę powiedzieć, ile razy napisałem podprogramy, aby zrobić części tego, co ten moduł może zaoferować, nie mogę go wystarczająco polecić. – slm
oddzielne dokumenty dla użytkowników i dokumenty dla programistów. może umieścić dokumenty użytkownika (tuts, faq, reference) w katalogu tam (/ doc) i kodery w tym samym kodzie. niestety jest to oczekiwane przez konwencję, aby mieć przegląd w samym module. to możesz, jak już określiłeś, zrobić POD po END. geny do kodowania dokumentów można wstawiać do komentarzy. dodatkowe rzeczy, takie jak styl kodowania lub jak włożyć wkład w osobne pliki .pod w bazie kodu (katalog główny?)
De gustibus. Osobiście wolę Doxygen (Doxygen :: Filter :: Perl) do POD. –