Если хорошо код документировать (по красивым и логичным правилам), то и документацию писать не надо - можно доверить это дело автоматическому phpdocumentor, и выглядит это дело вполне неплохо!