phpDocumentor на унаследованный код

Question

Можно ли использовать phpDocumentor для создания HTML-документов для какого-либо устаревшего кода, который не обязательно соответствует его стандарту?

Я хотел бы сгенерировать некоторую предварительную документацию для старого дерева кода, а затем начать улучшать мойкомментарии и добавьте соответствующие теги @, когда я свободно владею phpDocumentor.Я никогда раньше не использовал этот программный продукт, и примеры, которые я нашел, фокусируются на том, как написать новый код, который соответствует его синтаксису, и генерировать файл HTML за файлом с параметром -f.

I 'мы установили последний phpDocumentor через установщик командной строки PEAR и попробовали этот маленький * .bat файл в Windows XP:

@echo off
phpdoc ^
    --directory "\\server\project\trunk" ^
    --target "C:\tests\project-doc"

... но это все, что я получаю:

PHP Version 5.3.5
phpDocumentor version 1.4.3

Parsing configuration file phpDocumentor.ini...
   (found in C:\Archivos de programa\PHP\pear\data/PhpDocumentor/)...

done
Maximum memory usage set at 256M after considering php.ini...
using tokenizer Parser
directory: ''  not found

Я также попытался сопоставить UNC-путь с буквой диска:

@echo off
phpdoc ^
    --directory "I:\" ^
    --target "C:\tests\project-doc"

... но:

PHP Version 5.3.5
phpDocumentor version 1.4.3

Parsing configuration file phpDocumentor.ini...
   (found in C:\Archivos de programa\PHP\pear\data/PhpDocumentor/)...

done
Maximum memory usage set at 256M after considering php.ini...
using tokenizer Parser
a target directory must be specified
 try phpdoc -h

Это сообщение об ошибке остается тем же, если я создаю "C: \"tests \ project-doc "перед.

Что именно неправильно в моем синтаксисе?

Answer 1

phpDocumentor действительно может работать с «недокументированным» кодом. Он создает свои документы на основе самого кода и использует блоки документов в качестве дополнительной информации (и дополнительной организации, в случае тегов @package и @subpackage).

Я бы посоветовал начать с phpDocumentor для существующего кода и поработать над очисткой получаемых предупреждений в файле errors.html - этот файл создается на верхнем уровне выходных документов, но это не так. никакой ссылки на него из выходных документов.

После того, как вы их очистите, вы можете запустить phpDocumentor с аргументом -ue (--undocumentedelements), который добавит новые предупреждения в errors.html, выделив (более подробно) вещи, которые еще нужно документировать в docblocks.

Теперь, что касается проблемы, с которой вы пытаетесь запустить программу для кода на общем диске, я не уверен, что там не так. Сценарий явно способен выполнять PHP и находить сам код phpDocumentor. Вы можете попытаться поместить аргументы в одну строку вместо использования ^ в качестве escape-символа перевода строки и, возможно, удалить кавычки вокруг путей (поскольку в путях нет пробелов).

Answer 2

Я думаю, что нашел проблему.Парсер параметров очень требователен и ему не нравятся ни UNC-пути, ни пустые корневые каталоги.Если я заменим это:

--directory "I:\"

... на это:

--directory "I:\."

... оно, наконец, начнет работать.

Полагаю, это ошибка.Их средство отслеживания ошибок не является общедоступным, поэтому я не знаю, является ли это известной проблемой.