Udało mi się znaleźć stronę z Safari Books Online, która zapewnia a template, ale nigdy nie pisałem komentarzy POD, nie jestem pewien, jak dobrze jest, lub jeśli brakuje czegoś, co może być uznane za konwencję do włączenia.Czy są jakieś konwencje dotyczące pisania komentarzy POD dla Perla?
Na jakich konwencjach należy pisać przy pisaniu POD dla skryptów Perla? Czy jest coś takiego jak Sun's Javadoc Conventions, ale dla komentarzy POD?
To nie jest skomplikowane, ale bardzo podoba mi się wprowadzenie Juerda na perlpodtut.
Autor wspomina o tym, co uważa za wspólne sekcje i co powinien zawierać.
Istnieje zestaw zaleceń w Perl Best Practices. Cały rozdział 7 obejmuje dokumentację, przy użyciu POD i najlepsze podejścia do dokumentacji modułów, dużych projektów itp. Mówi także o konwencjach CPAN. To prawdopodobnie twój najlepszy zakład.
Perl::Critic zapewnia następujące zasady:
A list of required sections jest dostarczana zgodnie z ostatnią polisą powyżej.
Module::Starter::PBP wygeneruje dla ciebie kod podstawy.
"Wskazówki do pisania" nie dotyczą treści. Prawdopodobnie powinienem edytować moje pytanie, aby było bardziej zrozumiałe, ale szukam treści i projektów (podział, nagłówek, wcięcia ...) konwencji. Patrzę na RequirePodSections, aby zmodyfikować szablon, którego szukałem, aby spróbować go poprawić. –
Tak, +1 dla domyślnych wymaganych sekcji dokumentu RequirePodSections. Używam go do modyfikowania oryginalnego szablonu, z którym się łączyłem. Myślę, że mam coś, co jest przyzwoite, co jest lepsze niż to, z czym zacząłem. –
Możesz spojrzeć na kapsuły pod moduły Perla pod numerem CPAN Search i szybko zauważyć, co każdy robi. Różne narzędzia do uruchamiania modułów tworzą dla Ciebie zestaw do montażu.
To prawie tak blisko, jak to tylko możliwe.
Czy wiesz, że jeśli którykolwiek z nich jest dostępny bezpłatnie w Internecie? Podoba mi się sugestia książki (zwłaszcza, że wygląda na bardzo kompletną i dogłębną), ale najlepiej będzie dostępne coś, co ułatwi mi pracę. –
@Thomas Owens: Nie sądzę, aby jakakolwiek treść książki była dostępna bezpłatnie w Internecie. Łącze Sinana do Perla :: Krytyka jest dobre. Inną opcją jest zapoznanie się z dokumentacją niektórych podstawowych modułów CPAN. Chociaż podejścia mogą się nieco różnić, istnieją standardowe sekcje itp., Które są pomocne jako wskazówki. –