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

Astral Man

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

Возникла идея документирования кода с помощю XML, например:
PHP:
/** 
     <file>
          <type>function</type>
          <name>Функция такая...</name>
          <version>0.0.1</version>
          ... и т.д.
     </file>
**/

/**
     <function name="myFunction"> 
          <var>
               <name>$var1</name>
               <desc>Переменная первая, для того-то...</desc>
          </var>
          <var>
               <name>$var2</name>
               <desc>Переменная номер два...</desc>
          </var>
**/
function($var1, $var2) {
     ....
}

/** </function> **/
Файл парсится (все что между '/**' и '**/'), получаем готовый XML и делаем с ним все что угодно.

Это актуально?
 

Astral Man

We Will Rock You
Про это я вкурсе. Я предлогаю использовать именно XML.

-~{}~ 29.06.05 12:19:

Автор оригинала: crocodile2u
phpDocumentor не устраивает?
Так и знал что сразу ссылки пойдут...
Я говорю про XML, про все эти документаторы мне известно.
 

crocodile2u

http://vbolshov.org.ru
получаем готовый XML и делаем с ним все что угодно.
Вот вопрос - что ты собираешься с ним делать?

И еще:
1. phpDocumentor стал, фактически стандартом документирования.
2. Комменты phpDocumentor-styled удобны
3. Лично мне будет НЕудобно писать вдобавок к пхп-коду еще и XML.
4. Комментарии в XML значительно менее читабельны. А ведь комменты - все же предназначены не для какого-то стороннего софта в первую очередь. А для программера, который будет этот _код_ читать.
 

Фанат

oncle terrible
Команда форума
crocodile2u, что за манера выискивать единственный рулез и молиться на него, как на икону?
ОДИН шабонизатор - смарти
ОДИН документатор
ОДИН язык - пхп
ОДНА бд - мускуль.
одна ос - линукс.
тебя не тошнит от этой ограниченности?

Комментировать - комментируй, но без фанатизма.
 

Astral Man

We Will Rock You
Фанат
А ты что по этому поводу думаешь? Интересно твое мение.
 

crocodile2u

http://vbolshov.org.ru
Фанат
Не понимаю, какая связь между топиком и ОС, а также смарти и БД.

Я привел phpDocumentor как знакомый мне софт. Может, я и правда, излишне на нем сосредоточился, хорошо, замечания остаются в силе:
3. Лично мне будет НЕудобно писать вдобавок к пхп-коду еще и XML.
4. Комментарии в XML значительно менее читабельны. А ведь комменты - все же предназначены не для какого-то стороннего софта в первую очередь. А для программера, который будет этот _код_ читать.
 

specialist

Guest
xml конечно хорошая штука, но в данном случае будет неудобно...имхо
З.Ы. присодиняюсь к kruglov
 

syfisher

TDD infected!!
По-моему, в DocBook есть стандартный набор тегов, которые предназначены для описания любого кода. Может лучше использовать их?
 

Фанат

oncle terrible
Команда форума
По-моему, ресторан МакДональдс предоставляет полный набор пищи, необходимой человеку. Может, лучше питаться только в макдональдсе?
 

StUV

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

crocodile2u

http://vbolshov.org.ru
+ к замечаниям, указанным ранее:
1. Едва ли найдется редактор, способный подсвечивать XML, находящийся внутри пхп-комментариев...
2. Я смотрю, на описание 1-го (!) параметра уйдет аж 4 строки минимум. Сравним это со следующим:
@param int $count Counter

-~{}~ 29.06.05 14:51:

StUV
Кстати, тоже хотел это предложить.
 

kruglov

Новичок
XML - эту универсальный стандарт. И как универсальный, он неэффективен в конкретных случаях, т. е. можно для данного случая разработать лучший формат.

-~{}~ 29.06.05 14:53:

И программисту еще за нестингом, соответствием открытых и закрытых тегов следить?
 

Astral Man

We Will Rock You
Автор оригинала: Frol
Astral Man
чем "XML" будет удобней phpdoc?
Может все это грамоздки... Зато засширяемо, и универсально.

-~{}~ 29.06.05 15:00:

Автор оригинала: kruglov
И программисту еще за нестингом, соответствием открытых и закрытых тегов следить?
А ты их сам отслеживать будешь или программно?
 
Сверху