Добро пожаловать в форум, Guest  >>   Войти | Регистрация | Поиск | Правила | В избранное | Подписаться
Все форумы / Delphi Новый топик    Ответить
Топик располагается на нескольких страницах: 1 2      [все]
 XML комментарий к юниту  [new]
Feg16
Member [заблокирован]

Откуда: دولة اسرا
Сообщений: 5412
Блог
Как правильно сделать комментарий, чтобы он отобразился в этом чертовом урезанном и беспантовом Code Insight? =)
///<summary>
///  Базовый класс создания модальных nagscreen
///</summary>
unit ufmBobBase;


К сообщению приложен файл. Размер - 16Kb
1 фев 13, 16:36    [13863001]     Ответить | Цитировать Сообщить модератору
 Re: XML комментарий к юниту  [new]
Feg16
Member [заблокирован]

Откуда: دولة اسرا
Сообщений: 5412
Блог
И заодно подскажите эксперт хороший, чтобы комментарий можно было в удобном окошке вводить, для домохозяек, а он сам потом сформировал нужный код :)
1 фев 13, 16:40    [13863033]     Ответить | Цитировать Сообщить модератору
 Re: XML комментарий к юниту  [new]
Arioch
Member

Откуда:
Сообщений: 11101
Feg16
И заодно подскажите эксперт хороший, чтобы комментарий можно было в удобном окошке вводить


Вообще-то это не CodeInsight, a Doc Insight
Соответсвенно, есди очешь окошка и поддержки разных тегов - надо покупать полную версию - http://www.devjetsoftware.com/products/documentation-insight/

Но я попробовал полгода назад триалку, посмотрел на глдюки - и вернул себе бeсплатный Express
1 фев 13, 18:57    [13863814]     Ответить | Цитировать Сообщить модератору
 Re: XML комментарий к юниту  [new]
Feg16
Member [заблокирован]

Откуда: دولة اسرا
Сообщений: 5412
Блог
А... полную версию, спасиб.
Arioch
Но я попробовал полгода назад триалку, посмотрел на глдюки
Вот и пропал весь запал задокументировать проект :(
1 фев 13, 19:18    [13863877]     Ответить | Цитировать Сообщить модератору
 Re: XML комментарий к юниту  [new]
Arioch
Member

Откуда:
Сообщений: 11101
я тут скачал helpndoc-setup
но пока не было времени

триалка бесплатная хоть на всю жизнь
и в рекламе все просто отлично

но... оно взеде отлично :-)
1 фев 13, 19:23    [13863893]     Ответить | Цитировать Сообщить модератору
 Re: XML комментарий к юниту  [new]
Arioch
Member

Откуда:
Сообщений: 11101
Feg16,

если хочешь комментами - можешь попробовать ожэивить такие проекты как

DiPasDoc
pasdoc
DelphiCodeToDoc
HTMLDOC
pas2dox + doxygen

Потом расскажешь, вдруг там правда все просто и все работает :-)
1 фев 13, 19:25    [13863897]     Ответить | Цитировать Сообщить модератору
 Re: XML комментарий к юниту  [new]
Feg16
Member [заблокирован]

Откуда: دولة اسرا
Сообщений: 5412
Блог
Arioch
Потом расскажешь, вдруг там правда все просто и все работает :-)
Спасиб! Утром попробую подобрать что попроще и поработоспособнее. А то стандартными средствами на _интерфейсную_ часть в 3 юнита - почти сутки ушли
1 фев 13, 19:27    [13863907]     Ответить | Цитировать Сообщить модератору
 Re: XML комментарий к юниту  [new]
Feg16
Member [заблокирован]

Откуда: دولة اسرا
Сообщений: 5412
Блог
Мне в принципе формировать выходной документ не нужно. Мне нужно чтобы я через полгода ткнув на класс прочел его описание, все зависимости / параметры / и т.п. и сразу приступил к работе, а не копался как же он подляк такой работает так хитро :)
1 фев 13, 19:30    [13863916]     Ответить | Цитировать Сообщить модератору
 Re: XML комментарий к юниту  [new]
GunSmoker
Member

Откуда:
Сообщений: 3231
1. Бесплатный Documentation Insight Express входит в состав Delphi последних версий (XE2+).
2. Референс-доки по XML комментам можно взять на сайте того же Documentation Insight.
3. Вместо Documentation Insight можно использовать Live Templates.
4. XML комментарии удобно заворачивать в $REGION.
5. Чтобы XML комментарий в модули подхватился Help Insight, модуль должен входить в состав проекта.
6. Самая проблема - гиперссылки на идентификаторы. В Delphi с этим неразбериха. Родной Help Insight использует один формат, родной же DocGen - другой. Формата два: "Unit.Class.Routine" и "Unit|Class.Routine". Рекомендую использовать второй.
7. XML комментарии могут быть преобразованы в документацию. Это можно сделать:
а). Встроенным средством. Честно - говно. Сложно заставить работать и, что главное, крайне сложно кастомизировать. Но - бесплатно и стандартное.
б). Doc-O-Matic. Результат - посредственный. Работает, кастомизировать можно, но в целом - "не вылизано".
в). DocGen-ом Documentation Insight 2 Enterprise. Вывод - HTML, CHM, MS Help 2, Help&Manual. Результат - отличный.

Ну и в целом глянуть.

P.S. Лично меня не устроили существующие решения генерации документации по исходному коду и я написал свой генератор на базе парсера касталии. Результат вывода можно посмотреть, к примеру, тут. Сырцы генератора я отдал автору Documentation Insight по его просьбе. Делал ли он свой DocGen на базе моего или писал с нуля - не в курсе.
1 фев 13, 20:09    [13864091]     Ответить | Цитировать Сообщить модератору
 Re: XML комментарий к юниту  [new]
GunSmoker
Member

Откуда:
Сообщений: 3231
Ну и терминология:

Help Insight - встроенная хрюля в IDE, которая показывает всплывающие подсказки при наведении мышью на идентификаторы. Подсказки создаются по XML-комментариям, если они есть, или автогенерируются пустые. Подсказка оформляется в соответствии с XML/XSL шаблоном. Шаблон можно заменить на свой.

Documentation Insight - сторонний IDE-эксперт к IDE, который был включён в стандартную поставку IDE, начиная с XE2. Показывает WYSIWYG-окно редактирования документации (XML-комментов) и заменяет XSL шаблон Help Insight на расширенный. Старшие версии имеют дополнительные пряники.

DocInsight - если только как сокращение Documentation Insight.
1 фев 13, 20:19    [13864115]     Ответить | Цитировать Сообщить модератору
 Re: XML комментарий к юниту  [new]
GunSmoker
Member

Откуда:
Сообщений: 3231
Code Insight - встроенная в IDE хрюля, которая помогает писать код. Состоит из Code Completion (Ctrl + Пробел, высвечивает список после точки), Code Parameters (Ctrl + Shift + пробел, показывает подсказку по аргументам) и Class Completion (Ctrl + Shift + C, завершает объявление класса).
1 фев 13, 20:22    [13864119]     Ответить | Цитировать Сообщить модератору
 Re: XML комментарий к юниту  [new]
GunSmoker
Member

Откуда:
Сообщений: 3231
Соответственно, чтобы ответить на исходный вопрос, надо:
1. Определится с терминологией. Code Insight не имеет отношения к комментам и документации. Он не может быть урезанным. Подсказки показывает Help Insight, и он - всегда встроенный. И поэтому тоже не может быть урезанным.
2. Определится с тем, какая стоит версия IDE, Documentation Insight (если есть) и какой установлен шаблон для Help Insight.
3. Проверить, является ли модуль с комментами частью проекта или же просто перечислен в uses.
1 фев 13, 20:26    [13864131]     Ответить | Цитировать Сообщить модератору
 Re: XML комментарий к юниту  [new]
GunSmoker
Member

Откуда:
Сообщений: 3231
Arioch, а чё за глюки? У меня ынтырпрайз стоит, вроде весьма стабилен. Про глюки лучше разработчику написать, поправит.
1 фев 13, 20:29    [13864138]     Ответить | Цитировать Сообщить модератору
 Re: XML комментарий к юниту  [new]
Arioch
Member

Откуда:
Сообщений: 11101
GunSmoker,

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

может быть с aqtime пересекался - он вроде много где глюки наводил
1 фев 13, 20:53    [13864222]     Ответить | Цитировать Сообщить модератору
 Re: XML комментарий к юниту  [new]
Arioch
Member

Откуда:
Сообщений: 11101
GunSmoker
4. XML комментарии удобно заворачивать в $REGION.


Зачем ? они же сами себе регионы ?
1 фев 13, 21:00    [13864249]     Ответить | Цитировать Сообщить модератору
 Re: XML комментарий к юниту  [new]
Arioch
Member

Откуда:
Сообщений: 11101
GunSmoker
Сырцы генератора я отдал автору Documentation Insight по его просьбе.


мог бюы и в сеть выложить, ты ж ему ,надеюсь, не эксклюзивно отдал ? :-)
1 фев 13, 21:02    [13864262]     Ответить | Цитировать Сообщить модератору
 Re: XML комментарий к юниту  [new]
GunSmoker
Member

Откуда:
Сообщений: 3231
автор
может быть с aqtime пересекался


Тащемта этот AQTime спокойно крешит даже чистую IDE, что уж говорить про нагруженную. Или может и не он крешит, а крешится IDE, а он только лезет отчёт отправлять. Но пинать все будут его...

автор
Зачем ? они же сами себе регионы ?


Сами по себе они не регионы.

///	<summary>
///	  Base unit for dialogs.
///	</summary>
///	<remarks>
///	  <para>
///	    This unit contains basic abstract class for implementing error dialogs in EurekaLog. It also registers build-in
///	    classes like NULL dialog and MessageBox dialog.
///	  </para>
///	  <para>
///	    Non-trivial error dialogs are implemented in other units (see below), which refers to this unit (EDialog) and 
///	    implement one or more child sub-classes.
///	  </para>
///	</remarks>


Это - не регион.

Чтобы это стало регионом (и чтобы его можно было сворачивать), надо добавить $REGION:

{$REGION 'Documentation'}
///	<summary>
///	  Base unit for dialogs.
///	</summary>
///	<remarks>
///	  <para>
///	    This unit contains basic abstract class for implementing error dialogs in EurekaLog. It also registers build-in
///	    classes like NULL dialog and MessageBox dialog.
///	  </para>
///	  <para>
///	    Non-trivial error dialogs are implemented in other units (see below), which refers to this unit (EDialog) and 
///	    implement one or more child sub-classes.
///	  </para>
///	</remarks>
{$ENDREGION}


Или даже так:

{$IFDEF SUPPORTS_REGION}{$REGION 'Documentation'}{$ENDIF}
///	<summary>
///	  Base unit for dialogs.
///	</summary>
///	<remarks>
///	  <para>
///	    This unit contains basic abstract class for implementing error dialogs in EurekaLog. It also registers build-in
///	    classes like NULL dialog and MessageBox dialog.
///	  </para>
///	  <para>
///	    Non-trivial error dialogs are implemented in other units (see below), which refers to this unit (EDialog) and 
///	    implement one or more child sub-classes.
///	  </para>
///	</remarks>
{$IFDEF SUPPORTS_REGION}{$ENDREGION}{$ENDIF}


Само собой, SUPPORTS_REGION ещё надо определить в опция проекта или .inc файле.

Documentation Insight автоматически добавляет регионы к XML комментам, это да. Но это - не "сами себе".

автор
мог бюы и в сеть выложить, ты ж ему ,надеюсь, не эксклюзивно отдал ? :-)


Не эксклюзивно, но:
1. Там страшный код, который писался два дня "лишь бы работало".
2. Он заточен под EurekaLog и там куча нестандартных правил для ссылок (к примеру, ссылки на внешний CHM).
3. Пока никто им не интересовался.

В свете наличия готового DocGen в Documentation Insight, который вылизан и заточен под Delphi, смысла в моей поделке для широкой публики я не вижу. Я бы и переключился на DocGen от Documentation Insight, но меня останавливает только несовместимость. У нас другой стиль справки и вот эти самые нестандартные правила оформления ссылок.
1 фев 13, 21:29    [13864389]     Ответить | Цитировать Сообщить модератору
 Re: XML комментарий к юниту  [new]
Arioch
Member

Откуда:
Сообщений: 11101
GunSmoker
Сами по себе они не регионы.


Я несомненно что-то делаю не так, но...
https://docs.google.com/folder/d/0B5BzBHTOWJouTDZrVGgweEJnV3M/edit?usp=sharing
1 фев 13, 22:42    [13864757]     Ответить | Цитировать Сообщить модератору
 Re: XML комментарий к юниту  [new]
GunSmoker
Member

Откуда:
Сообщений: 3231
Это только в XE2+. В XE и ниже XML-комменты - не регионы.
1 фев 13, 23:07    [13864880]     Ответить | Цитировать Сообщить модератору
 Re: XML комментарий к юниту  [new]
Arioch
Member

Откуда:
Сообщений: 11101
GunSmoker,

но мне показалось, что автор про хе2+ и говорит, ведь раньше на борту Doc Insight Express не было...
1 фев 13, 23:13    [13864917]     Ответить | Цитировать Сообщить модератору
 Re: XML комментарий к юниту  [new]
GunSmoker
Member

Откуда:
Сообщений: 3231
Без понятия, что у автора. А DI поддерживает D7+.
2 фев 13, 00:34    [13865115]     Ответить | Цитировать Сообщить модератору
 Re: XML комментарий к юниту  [new]
Arioch
Member

Откуда:
Сообщений: 11101
GunSmoker,

но "из каропки" идет только с хе2. А автор явно не знал, что него там такое стоит.
Если бы это была Д7 - его первая враза была бы сильно другой :-)
2 фев 13, 01:42    [13865256]     Ответить | Цитировать Сообщить модератору
Между сообщениями интервал более 1 года.
 Re: XML комментарий к юниту  [new]
Benten
Member

Откуда: Россия, Крым
Сообщений: 26
Добрый день всем форумчанам!
Хотел бы актуализировать вопрос, поднятый много лет назад.
Умышленно не стал создавать новую тему, чтобы видеть историю
Спасибо многоуважаемому @GunSmoker за подробное разъяснение про Document Insight
GunSmoker
1. Бесплатный Documentation Insight Express входит в состав Delphi последних версий (XE2+).
....
Ну и в целом глянуть.
У меня есть несколько вопросов, ответы на которые возможно заинтересуют многих:
1. Что-то я не нашел бесплатного Documentation Insight Express в составе Delphi Sydney 10.4.2, плохо искал или убрали?
2. Насколько актуален Document Insight для последнего Embarcadero Delphi Sydney 10.4.2, корректно ли последний DocInsight работает в Delphi 10.4.2?
3. Есть на сегодня другие, не менее интересные решения для редактирования и генерации документации из XML-комментов?
4. Сталкивался ли кто-нибудь с тем, что в 10.4.2. сломали отображение встроенной подсказки Help Insight на базе xml-комментов?
В 10.3.3 еще работает, проверял.
26 май 21, 18:38    [22327624]     Ответить | Цитировать Сообщить модератору
 Re: XML комментарий к юниту  [new]
Benten
Member

Откуда: Россия, Крым
Сообщений: 26
Уже пробую Documentation Insigt Ultimate 3.10.12.16 в Delphi Sydney 10.4.2.
Пока все работает. Посмотрю, что дальше ...
Если понравится, буду покупать :-))

К сообщению приложен файл. Размер - 110Kb


Сообщение было отредактировано: 26 май 21, 23:44
26 май 21, 23:50    [22327739]     Ответить | Цитировать Сообщить модератору
 Re: XML комментарий к юниту  [new]
asutp2
Member

Откуда: Тюмень
Сообщений: 852
Benten,

В 10.4.2 завертывание в {$REGION 'Document'} по большому счету уже и не нужно, т.к. IDE позволяет нормально схлопывать само xml-описание, по аналогии с region

Сообщение было отредактировано: 27 май 21, 09:20
27 май 21, 09:23    [22327803]     Ответить | Цитировать Сообщить модератору
 Re: XML комментарий к юниту  [new]
asutp2
Member

Откуда: Тюмень
Сообщений: 852


К сообщению приложен файл. Размер - 11Kb
27 май 21, 09:29    [22327804]     Ответить | Цитировать Сообщить модератору
 Re: XML комментарий к юниту  [new]
DmSer
Member

Откуда: Пенза
Сообщений: 1376
Оно автоматически в свёрнутом состоянии открывается, или нужно что-то нажимать?
27 май 21, 09:57    [22327814]     Ответить | Цитировать Сообщить модератору
 Re: XML комментарий к юниту  [new]
энди
Member

Откуда: Киров, Россия
Сообщений: 1249
кстати, а есть что-то из экспертов что работает с регионами, что-то несложное, типа свернуть все регионы по открытому модули, развернуть все и т.д? Ну и чтобы хоткеи были естественно.
27 май 21, 11:27    [22327855]     Ответить | Цитировать Сообщить модератору
 Re: XML комментарий к юниту  [new]
asutp2
Member

Откуда: Тюмень
Сообщений: 852
DmSer
Оно автоматически в свёрнутом состоянии открывается, или нужно что-то нажимать?
По умолчанию изначально всё в открытом состоянии, но если схлопнуть, то IDE хранит инфу и при последующем открытии модуля автоматом откроется в свернутом виде
27 май 21, 12:54    [22327920]     Ответить | Цитировать Сообщить модератору
 Re: XML комментарий к юниту  [new]
_Vasilisk_
Member

Откуда: Украина, Харьков
Сообщений: 12885
энди
что-то несложное, типа свернуть все регионы по открытому модули, развернуть все
Из коробки по правой кнопке мыши

К сообщению приложен файл. Размер - 29Kb
27 май 21, 13:03    [22327928]     Ответить | Цитировать Сообщить модератору
 Re: XML комментарий к юниту  [new]
энди
Member

Откуда: Киров, Россия
Сообщений: 1249
хоткеи можно назначить?
27 май 21, 13:12    [22327935]     Ответить | Цитировать Сообщить модератору
 Re: XML комментарий к юниту  [new]
Fr0sT-Brutal
Member

Откуда:
Сообщений: 755
энди
хоткеи можно назначить?

Да
27 май 21, 13:59    [22327967]     Ответить | Цитировать Сообщить модератору
 Re: XML комментарий к юниту  [new]
Benten
Member

Откуда: Россия, Крым
Сообщений: 26
asutp2
Benten,
В 10.4.2 завертывание в {$REGION 'Document'} по большому счету уже и не нужно, т.к. IDE позволяет нормально схлопывать само xml-описание, по аналогии с region
Да, спасибо, вроде работает без {$REGION 'Document'}, но это и не так важно по сравнению с жабой выложить 250 баксов :-)))
27 май 21, 14:33    [22327995]     Ответить | Цитировать Сообщить модератору
Топик располагается на нескольких страницах: 1 2      [все]
Все форумы / Delphi Ответить