Документирование кода с помощью XML

[Astral Man]

Автор оригинала: Frol
Astral Manок, повторю вопрос.
_чем_ будет удобней?

__засширяемо, и универсально__

 

[StUV]

Astral Man
ты считаешь, что распарсить пхпдок намного сложнее, чем загромождать код такими вот комментами

/**
<file>
<type>function</type>
<name>Функция такая...</name>
<version>0.0.1</version>
... и т.д.
</file>
**/

+ париться их написанием
?

 

[Astral Man]

http://users.freenet.am/~dotnet/csharp/csharp5.htm

 

[Sad Spirit]

Автор оригинала: Фанат
crocodile2u, что за манера выискивать единственный рулез и молиться на него, как на икону?

Фанат, не передёргивай.

ОДИН шабонизатор - смарти

С какого бодуна?

ОДИН документатор

Один стандарт документирования. Парсеров же для него даже в PEAR было 2 (до недавнего времени).

Поддерживается существующими редакторами / IDE. Напишет ли аффтар плагины для них под свой XML?

ОДИН язык - пхп

ви таки хотите погово'ить здесь за ASP?

ОДНА бд - мускуль.

Один стандарт --- SQL.

одна ос - линукс.

один стандарт --- POSIX


По существу вопроса: phpDocumentor замечательно умеет генерировать DocBook XML по комментариям. Я через это уже несколько пакетов PEAR задокументировал.

Предвосхищая следующий наезд про "один XML --- DocBook": DocBook, в отличие от доморощенного XML таки да тоже стандарт, поддерживаемый кучей инструментов.

 

[Astral Man]

DocBook, в отличие от доморощенного XML таки да тоже стандарт, поддерживаемый кучей инструментов.

А помоему XML - это стандарт, а DocBook "типа" стандарт документирования используя технологию XML.
И вообще-то обратите внимание на название топика.

 

[kvf77]

Astral Man
я вот никак не пойму - ты хотел услышать мнения людей - услышал - а все остальное уже на святую войну похоже - типа обидели - не оценили. Для меня лично главный довод - неудобно код смотреть и читать такие комменты - придется для просмотра кода пользовать всякие спец. проги - нафиг оно надо? Вообще не понимаю зачем сувать XML везде, он тут нафиг не нужен

 

[crocodile2u]

Astral Man
XML - стандарт. А вот этот надуманный "CommentML" - вовсе не стандарт.

Впрочем, комментируй, как хочешь.

 

[Astral Man]

Все понятно...

 

[Crazy]

Автор оригинала: crocodile2u
1. Едва ли найдется редактор, способный подсвечивать XML, находящийся внутри пхп-комментариев...

Требуется:

1. vim
2. руки, растущие из правильного места
3. 15 минут времени

 

[palych063]

PhpDocumentor->XMLocbookeardoc2

Автор оригинала: StUV
Astral Man
imho, было бы удобнее делать комменты в стиле пхпдокументатора, а при парсинге (по необходимости) генерить соотв. хмл - а потом делай с ним что хочешь...
(из доводов - все 4 от crocodile2u)

Было бы здорово если бы объяснили как это работает, и работает вообще

 

[demongloom]

Имхо:
1. Громоздко.
2. Запаришся писать вручную все эти хмл теги. (Если редактор не позволяет)
3. В чем выгода?

 

[Crazy]

Автор оригинала: demongloom 1. Громоздко.

При редакторе с фолдингом -- не проблема.

2. Запаришся писать вручную все эти хмл теги. (Если редактор не позволяет)

Не нужно пользоваться плохими редакторами.

3. В чем выгода?

В расширяемости.

 

[palych063]

Может кто-нибудь подскажет как генерить XML с помощью phpDocumentor, ибо у меня не получается, с html нет проблем, а вот XML......

 

[Alexandre]

Возникла идея документирования кода с помощю XML

NetStudio -для этого есть уже определенный аппарат
определенные теги в ввиде xml , аналог явадок
возможность генерить HTML - аналог явадок (пхпдокументатор)

можно его изучить и пользоваться им

так же, есть плагин NetStudio для PHP
так что остается пересесть на NetStudio и часть проблем решена

 

[Sherman]

Если бы ты написал модуль к Zend studio, в котором шаблон для документирования генерировался автоматически, а нужно было бы вписать только значения, то это было бы удобно. Или же хотя бы парсер, который, пройдясь по файлу с исходным кодом, создал бы документацию к нему. Ну и заодно уже прогу, которая могла бы публиковать код на веб-узле. А так это всего лишь еще одна идея.

Кстати, твой формат отдаленно напоминает XML-RPC(точнее вызов функции удаленно)

 

[demongloom]

В расширяемости.

Расширяемости чего? Подсознания?
Каких тегов вам не хватает и чего нельзя обычным образом описать в description поле?

Зачем писать многие вещи дважды да еще и громоздко?
/*
<function name="aaa">
<type>static</type>
<access>public</access>
<version>0.0.1</version>
<author>vasya pupkin</author>
<description>Returns sum of A + B</description>
<variables>
<variable name="a" type="integer" />
<variable name="b" type="integer" />
</variables>
*/
static public function aaa($a, $b) {
return $a + $b;
}
/*
</function>
*/
3 раза пишется только слово function, дважды пишется имя.
Соответственно если эта функция будет в классе и будет иметь различные атрибуты в виде static, final их тоже надо будет писать? А также перечислять каждую переменную? И в результате только тегов хмл будет больше чем код самой функции.

Намного изящней и удобочитабельней:
/**
Returns sum of A + B

@author Vasya Pupkin
@version 0.0.1
@param Int $a, Int $b
@return Int
*/
static public function aaa($a, $b) {
return $a + $b;
}

static, public и прочее указывать ненужно. Хороший редактор сам покажет какого типа функция. А если смотреть в коде коммент, то сам код функции показывает какого она типа.

P.S.
Видать хороший урожай конопли в этом году.

P.S.
Вы хоть представьте себе исходники ядра линукс документированные вышеуказанным методом. Они не 40 мег в бзипе, а 120 весить будут.

 

[IntenT]

Я так понимаю, автор предлагает озадачиться кроме всего прочего еще и проблемой валидности XML?

 

[Alexandre]

Идея документирования XML не нова и правильная

phpDocumentator является аналогом яваДок
в эпоху становления ява , XML еще не был изобретен, и по этому придумали использовать @

а многие идеи ява - перешли в РНР
придет время - и будет документирование PHP в XML

как я писал, NET Studio эту проблему уже решило.

Я не предлагаю поголовно пересесть всем на NET Studio, я просто привожу пример хорошего продукта и продвинутой идеи документирования.

 

[palych063]

По поводу NET Studio можно поподробнее?
Кстати phpDocumentator позволяет документировать PHP в XML (XML:docBook).

 

[kruglov]

Ну, документирование сильно облегчается, если используется не блокнот, а специализированная среда. Которая при комментировании функции показывает специальный интерфейс с нужными полями, чтоб ничего не забыть и не опечататься. А уж как она будет сохранять комментарии, в XML или нет, уже не столь существенно. Тут XML даже лучше, незнакомый человек скорее догадается, где тут что.