phpDocumentor i MVC, dokumentacja dla kontrolera Opcje

[Xathloc]

Podczas dokumentowania projektow mam niedomiennie ten sam problem. PHPDocumentor generuje z założenia dokumentację dla klas. Kontroler klasą nie jest i co za tym idzie jest ignorowany podczas tworzenia dokumentacji. Dla mnie kontroler, jako element spinający całość, jest najlepszym miejszcem do zawarcia najobszerniejszego opisu.
Jak wy rozwiązujecie problem dokumentacji kontrolera i całości aplikacji/modułu? Czy korzystacie z innych narzędzi?
Jak dla mnie PHPDocumentor jest najwygodniejszy, bo znajduje się w ZDE, którego używam.

[dr_bonzo]

Przenosze na php

[marast78]

ja używam wzorca FrontController(a możesz użyć Application Controller) i Strategy, i kontoler jest u mnie klasą, przynajmniej tak jest w rozwiązaniach webowych (poparte literaturą stiwerdzenie Czym jest kontroler?) choć tak naprawdę jest on pewnym mechanizmem otrzymania i interpretacji żadania (z HTTP, klawiatury itp.) przekazując je do odpowiedniego modelu lub widoku, lecz czy nie może być klasą? więc nie ma problemu, żeby wygenerować z nich dokumentację używająć PHPDoc, nie rozumiem jednego więc czym u ciebie jest kontroler, jak wygląda w implementacji (u mnie jest klasą) używając MVC rozumiem, że piszesz aplikację obiektowo u mnie klasa ta ma metodę która automatycznie wykrywa jaki obiekt ma zainicjalizować i tu pomocy jest model DAO, poza tym weźmy na to przykład z javy, gdzie rolę kontrolera spełnia Servlet więc jest on klasą... No więc czy kontroler w rozumieniu programisty php nie jest klasą

[Xathloc]

Kontroler może być klasą, ale często wygodniej jest kiedy przyjmie postać prostego switch'a (wszystko zależy od aplikacji/modułu, który tworzymy). U mnie przypadek ten stanowi ok. 80% zleceń. Dlatego też szukam dobrej metody na dokumentowanie tego typu aplikacji/modułów.
Czasem nie warto tworzyć stuktur, które są zbyt rozbudowane i "poważne" do stawianych przed nimi zadań.

[marast78]

na switchu i po co się tak męczyć po to są wzorce, żeby mieć więcej wolnego czasu no chyba, że twoje akcje to jakieś pojedyncze instrukcje...

Ten post edytował marast78 20.10.2006, 14:57:11

[Xathloc]

na switchu i po co się tak męczyć po to są wzorce, żeby mieć więcej wolnego czasu no chyba, że twoje akcje to jakieś pojedyncze instrukcje...

Zależy od konkretnego przypadku. Ale jak pisałem, w 80% przypadków kontroler nie jest specjalnie rozbudowany. Wzorce owszem, warto stosować, ale wtedy kiedy złożoność aplikacji to uzasadnia. A dokumentacja przydaje się niezależnie od złożoności (no może bez przesady ^^). I ciężko mi jest bez niej rozwijać moduł kiedy Klient zażyczy sobie po roku nowej funkcjonalności.

[dr_bonzo]

Switch jest najbeznadziejniejszym rozwiazaniem.

Juz lepiej wrzucic mapowanie nazyw akcji do pliku.
np:
include( $mapa_akcji[ oczysc_nazwe_akcji_z_niebezpiecznych_znakow( $_GET['akcja' ] ) ] );
(gdy dodajesz kolejna akcje to wystarczy dodac kolejny element tablicy:
$mapa_akcji[ 'new_action' ] = "../sciezka/plik.php" + utworzyc plik z akcja

Idac dalej: nazwapliku moze byc identyczna jak nazwa akcji
include( oczysc_nazwe_akcji_z_niebezpiecznych_znakow( $_GET['akcja' ] ) ] . 'php' );
+ sprawdzenie czy plik istnieje
dodanie nowej akcji to tylko dodanie pliku z akcja

Lub jeszcze (jak pisal marast78):
kazda akcja to osobna klasa (jak w Agavi/Mojavi), lub metoda kontrolera (Symfony, RoR , ZF)
dodanie nowej akcji to tylko dodanie pliku z klasa akcji, no i masz wieksze mozliwosci niz przy zwyklym includowaniu


A w switchu? Musisz edytowac KOD skryptu i dodac nowe pliki. Po co to robic gdy wystarczy tylko utworzyc plik z akcja?

[Xathloc]

A w switchu? Musisz edytowac KOD skryptu i dodac nowe pliki. Po co to robic gdy wystarczy tylko utworzyc plik z akcja?

Zaraz, jako to?
A czym się różni utworzenie nowego pliku z akcją od dodania akcji do switch'a?
Tak czy inaczej muszę nauczyć odbiornik, że pojawiła się nowa akcja i utworzyć dla niej kod. Przy niezbyt rozbudowanych projektach zaczyna się pojawiać więcej kodu obsługującego framework niż wykonującego czynności wymagane z punktu widzenia modułu.
Zgadzam się, że switch'e dla dużych projektów są niewygodne (ale nie najbeznadziejniejsze).

[dr_bonzo]

Jwsli w switchu wykonujesz max 1-5 instrukcji (dla pojedynczej akcji) to jeszcze moglbym to przebolec.

[Xathloc]

Jwsli w switchu wykonujesz max 1-5 instrukcji (dla pojedynczej akcji) to jeszcze moglbym to przebolec.

Dokładnie o tym mówię ^^ Są sytuacje, kiedy budowanie osobnych klas, mapowanie itp. nie mają sensu. Jednocześnie ilość akcji może być całkiem spora, no i trzeba to jakoś odokumentować
I tu powraca moje pytanie.

Ale z tego co widzę, to MVC raczej używane jest przez was do projektów dużych i bardzo dużych.
Dla mnie jest to prosta metoda zachowania porządku w aplikacji/module każdej wielkości, ułatwienie pielęgnowania kodu i rozwoju. Może faktycznie jest to uproszczony model MVC, ale nadal zgodny z założeniami

[dr_bonzo]

Tzn. masz tego switch'a w glownym pliku, poza jakakolwiej funkcja i chceszgo zdukumentowac?
Tak sie nie da.

Wrzuc to wszystko w jedna klase, a kazda akcje wstaw do osobnej funkcji:

[PHP] pobierz, plaintext 
<?php
function dispatch()
{
 
  switch()
 { 
	 case "costam" : $this->costam();
	 case "....
}
}
?>
[PHP] pobierz, plaintext 

// choc i tak przyda sie automatyczne wywolywanie funkcji

No i teraz masz funkcje klasy ktore phpdoc zauwazy.

[Xathloc]

Tak, ale wracamy do punktu wyjścia.
Chyba faktycznie phpDoc zmusi mnie do robienia wszystkiego porządnie i tworzenia klasy kontrolera zamiast kontrolera strukturalnego
W każdym razie dziękuję wam za pomoc.
I zmuszenie do porzucenia nieprawidłowych nawyków
Ale to już w wersji 1.1 tego modułu
1.0 własnie rusza do Klienta.