Jaki jest najlepszy sposób użycia: @package, @subpackage i @category

Czytam na phpdoc.org i nie bardzo rozumiem najlepszy czas na użycie @package, @subpackage i @kategorii. Jak na ironię, dokumentacja/przykłady nie są tak pomocne. Czy to tylko ja?Jaki jest najlepszy sposób użycia: @package, @subpackage i @category

Jeśli to pomaga, mam główny projekt (np. Motyw WordPress). Temat ten został opracowany w ramach drugiego projektu, którym jest biblioteka klas. Ta biblioteka jest dodatkowo podzielona przez typ obsługiwanej przez nią funkcjonalności. Na przykład folder classes zawiera podfoldery: Theme, Taxonomies, Search itd.

Podfoldery te wydają się być dobrym kandydatem do kategorii, ale przykłady phpdoc dla @subpackage i @category nie są dla mnie zbyt jasne. Jeśli o to chodzi, definicja @package nie jest dokładnie taka, jakiej oczekiwałbym od dokumentacji dokumentacji narzędzia do dokumentacji.

Odpowiedzi i wszelkie dobre linki, które pozwolą szybko przejść na wyższy poziom, będą bardzo mile widziane. Dzięki

Źródło

2013-03-31 Chief Alchemist

@subpackage jest upuszczany w najnowszych wersjach PHPDoc, więc nie powinno to już być problemem; ale jeśli chcesz zapytać, prawdopodobnie nie chcesz ich używać; ale prawdopodobnie używałbyś jednego wspólnego tagu, a ja kategoryzowałbym według tematów, taksonomii itp. –

OK, dzięki @MarkBaker. Więc w moim przypadku temat byłby na opakowaniu, a biblioteka byłaby inna. i w każdym z nich użyłbym kategorii @, aby pomóc narzędziu phpdoc w organizowaniu modułów/plików w strukturze każdego z nich? Brzmi nieźle? Czy jest coś jeszcze, co polecasz? Nie zamierzam wychodzić na całość, ale chcę zachować pewne minimalne standardy, które pomogą uczynić któryś z projektów użytecznym dla innych. Odkomentowany kod to mój ulubiony zwierzak. Nie chcę być tym gościem. –

@kategoria jest rzeczywiście rzeczą "grupowania pakietów", jednak żaden z konwerterów wyjściowych phpdoc 1.x w żaden sposób nie wykorzystuje tej grupy. Tylko przypadek @package i @subpackage ma znaczenie w phpdoc 1.x.

W phpdoc 2.x, przestrzenie nazw są królem. Pakiet/podpakiety były formą wyświetlania nazw, ponieważ PHP < 5.3 nie zawierało w niej żadnych przestrzeni nazw. W związku z tym prawdopodobnie zobaczysz, że wsparcie dla @category, @package i @subpackage całkowicie wypada z phpdoc 2.x.

Aby uzyskać rodzaj grupowania udokumentowanych elementów, wybór mechanizmu grupowania zależy od tego, jakiego narzędzia używasz. Będziesz potrzebował tylko pakietu @ package/@ subpackage, jeśli używasz phpdoc 1.x. Jeśli jednak Twój kod wynosi 5.3+, tak, że korzystasz z phpdoc 2.x, lepiej jest używać przestrzeni nazw w kodzie.

Źródło

2013-04-01 20:36:28 ashnazg

Thx @ashnazg. Prawdę mówiąc, w tej chwili nie używam narzędzia do pisania *. Z pewnością w czasie, który może się zmienić. W międzyczasie staram się rozwijać dobre nawyki, a także tworzyć kod przyjazny dla GitHub. Oznacza to, że jeśli inni je rozwiążą, będzie im łatwo z nimi pracować, jeśli używają narzędzia doc. Ma sens? Biorąc pod uwagę ten kontekst, jeśli masz sugestie, splunij na mnie. –

Nawet w tym sensie przestrzenie nazw są królem. Jeśli Twój kod nie ma być oznaczony jako 5.3+ lub nazwany, wtedy użycie pakietu jest mniej więcej tak, jak bym zasugerował. Wartość umieszczona w znaczniku pakietu może zawierać separatory (ukośnik odwrotny, kropka, podkreślenie), dzięki czemu można wyświetlać je jako oddzielne poziomy: * at-package Foo \ Bar \ Baz * pakiet foo.Bar d spróbuj uzyskać za pomocą tego rodzaju schematu najpierw, przed rozważeniem dodania podpakietu do miksu. – ashnazg

dzięki jeszcze raz @ashnazg. Czy mogę używać separatorów w kategoryzacji jako proxy dla podpakietów, a nawet kategorii? To działa dla mnie. Jak już wspomniano, uważam, że kod "nadający się do spożycia" jest ważny i staram się, aby było to jak najłatwiejsze - oprócz rzetelnych komentarzy - aby ułatwić komuś zrozumienie. btw, jeśli znasz jakieś linki do dobrych przykładów/przykładów, które byłyby bardzo mile widziane. Twoje zdrowie. –

Jaki jest najlepszy sposób użycia: @package, @subpackage i @category

Odpowiedz

Powiązane problemy