XML-документация

[nikedeforest]

Вот создал я XML-документация к проекту, файл создался. Все хорошо. А вот как бы теперь так сделать, чтобы этот файл ХМЛ мне представили в каком-то более красивом/читабельном ввиде, чисто уже для пользования человеком?

[Sla]

преобразовать его в XHTML

[nikedeforest]

Что-то мне подсказывает, что есть инструмент от Майкрософт, который позволяет перевести эту документацию в doc, к примеру. Только то ли ее нет в составе Студии, то ли я плохо искал.

[RXL]

nikedeforest, да-да. Создай xsl-файлик, в котором будут описаны преобразования твоего xml в html.

В атаче примерчик - мои потуги 4 года назад перевести статьи в xml.

[Sla]

Вот скажи для чего ты сделал в XML? Для крутости или для совместимости?

Думаю что для второго.

Т.е. ты этот документ можешь прочитать везде. Вернее, данные твоего документа подготовлены для машинной обработки.

[Джон]

Слав, в студии XML код генерируется автоматически из коментариемв в специальном формате. Тут выбор не богат.

nikedeforest, XSLT самое надёжное решение. Для 2005 студии есть примочки.

[nikedeforest]

Да, Джон, все правильно. Расскажу в чем суть. Когда работаешь в Студии, если придерживаться опеделенного форматат для создания окмментариев, то Стуляи потом на основе  этого комментария создаст этот ХМЛ-файл, который предполагается использовать для построения документации. Раньше в составе Студии шла примочка, но она не работала и видимо ребята из Майкрософт решили отказаться от нее. Взамен есть проект SandCastle. Он вроде открытого кода и вроде там даже приложило руку МАйкрософт. Установил, запустил, попробовал, не получилось, лег спать. Сечас буду уже точнее разбираться.

[nikedeforest]

Скажем прямо разочарован я SandCastle. Маленькую сборку онаодолела. А вот оснвоную сборку нет, при чем споткнулась она на форме на которй всего одна кнопка. Пытался найти способ задать исключения, чтобы она не анализировала этот класс, ничего не вышло.

[Алексей++]

а объясните мне, темноте, про что речь ? Не могу понять (

[Dimka]

Алексей1153++, тебя это не касается, в 6-й студии такого нет

[Алексей++]

ну и что, что нету ? Комментарии и классы я тоже пишу, бывало

[nikedeforest]

Народ, ну а что вы используетет в своей работе? Неужели не создаете подобных справочников, ведь удобно весьма?

[Dimka]

nikedeforest, я не создаю. Сама студия внутри проекта показывает подсказки ко всему.

[Джон]

а объясните мне, темноте, про что речь ? Не могу понять (

Лёш, ну вот ты ты MSDN пользуешься? Там всякую помощь по объектам, ф-ям и тд вызываешь? Там у тебя стоит что каждый параметр означает, какие значения может принимать и тд. Точно так же можно документировать свои собственные классы. Для этого в студию встроен механизм создания и сбора особого рода коментариев с ключевыми словами. Если придерживаться этого правила, то студия сможет выдрать эти коменты из твоего кода и сохранить в XML формате. Потом, обычно с помощью файла правил XSLT, из этого файла можно сделать HTML файл справки.

Народ, ну а что вы используетет в своей работе? Неужели не создаете подобных справочников, ведь удобно весьма?

Но стОит времени... Пока на сегодняшний день просто автоматически добавляем коментарии, чтобы потом, когда-нибудь, оглянувшись, стало мучительно больно за бесцельно потраченное время. Реально пока ешё ни разу подобного рода документация не понадобилась. Поэтому увы...

[nikedeforest]

dimka, я понимаю. Подказуи показываются, не вопрос, но не для этого треба, а для создания справочника. Sandcastle создает как раз именно то, что надо. Но оборотная сторона OpenSource, что не всегда работает .
Джон, я как раз твоего ответа и ждал. Че-то ...., разачарован немного .
Но учитывая, что майкрософт само не особо запарилось по поводу созлания подобного продукта, видимо это почти никому и не треба.

[Dimka]

nikedeforest, справочник нужен для чего? Чтобы им пользовались. Во всех проектах, с которыми я сталкивался, программисты смотрят не справочник, а сам код (в котором эти комментарии находятся). И я, например, не вижу никаких существенных аргументов за то, чтобы смотреть именно справочник, а не код.

Всё равно ж в этом справочнике не более чем перечень классов и их содержимого. Ни поиска, ни хотя бы индекса, ни обзорных статей типа "введение в архитектуру" или "основная идея модуля". Т.е. такой справочник получается менее содержательным, чем код, но удобство пользования им не выше, чем просто посмотреть в коде. Отсюда и результат - на практике этим мало кто пользуется (только если кто-то поставляет кому-то сборку без исходников - тогда такой документ в приложении полезен).

[nikedeforest]

Согласен, но тем не менее бывают случаи, когда используешь давно написанный класс или сборку и хотелось бы освежить в памяти методы, их описание. Получить такой малнький МСДН. Т.е. эьто тот случай, когда код-то и не нужен, нужно просто перечисление и описанине.

[Алексей++]

Джон, nikedeforest, смысл понятен... Но мне это не пригодится , похоже, я и так всегда перепрыгну на определение мембера и там всегда прочитаю комментарий

[Джон]

Джон, я как раз твоего ответа и ждал. Че-то ...., разачарован немного .

Дык тут ыть такое дело... Мы делаем проекты на заказ, те заказчику принадлежат все потроха, сырцы включая. Наивно полагая, что этими сырцами он когда-либо сможет воспользоваться. Тут скорее требование политическое, чем практическое.
Мы ещё не разу код не повторяли, чтобы повторно пользоваться сложными, для конкретного заказчика разработаннмыми, объектами, да и как правило принадлежат эти разработки ему же. Грубо говоря сделал - забыл. А вот заказчику самому тоже такая инфа до фени. Поэтому мы просто предпринимаем необходимые шаги, чтобы при необходимости такую документацию создать, но реально дальше этого ещё не заходило, так что тут я теоретический подкован, а практически - ноль. Да и задним умом понимаешь, что толк может быть только в том случае, если АБСОЛЮТНО ВСЁ хорошо коментируется. На практике это не достижимо. Благо 2005 студия ругается уорнингами, дескать там забыл, там число параметров не совападает и тп. А помню под 6ой студией тоже примочка какая-то была, только коменты надо было самому забивать (без наворчек в редакторе) и до того меня это достало, что я просто с шефом так сказать поспорил, что ежели когда документация на код понадобится, я в своё свободное время весь свой код необходимым образом закомментирую. Пока не проспорил.

А для самих себя любимых - действует принцип разумной достаточности, сложные места всё-равно коментируются, а создавать электронную справку - времени нет. Для фирм продающих именно модули, библиотеки классов и элементов управления (контролов) это есть обязательно, но не все таким видом деятельности занимаются.

[Dimka]

Получить такой малнький МСДН.

Так не получишь. Мощь MSDN в индексах, а с некоторо времени и в тщательной организации оглавления, в наличии обзорных статей, от которых и в которые идут ссылки из описаний кода, в подробном документировании каждого метода: общее описание, каждый параметр, результат, возможные исключительные ситуации, примеры использования на разных языках, ссылки на смежные (используемые и использующие) классы и методы.

Чтобы твоя справка превратилась в такое хотя бы даже по уровню описания методов, нужно очень много и очень тщательно комментировать, и, как сказал Джон, для таких трудозатрат нужно веское обоснование: я бы сказал, неизбежность будущей потребности в такой справке.

В подавляющем большинстве случаев неизбежности нет, поэтому никто так не делает.

[nikedeforest]

dimka, ты утрируешь . Я не писал о детальном хелпе с примерами и прочем. Но краткое описание и перечисление с возможностью перемещения по ссылке к другим типам, на которые ссылается текущий тип нахожу весьма полезным. Тем более, что сейчас затраты уже не столь велики и почти ничем не отличаются от правил документирования кода. Готовый шаблон выскочил, записал что делает метод, какие параметры принимает, какие возвращает (шаблон уже все выкидывает). Без параметров и возвращаемого значения всего одна строка, ну и если что, якорь на другой тип, считай вторая.
Джон, всей специфики вашей деятельности не знал. Ну тогда понятно, если ты свой код никогда
больше не увидишь и не задействуешь, то необходимости на самом деле нет.

[Malaja]

Пардон, что с полугодовым опозданием (я тему прозевала), но может кому-то понадобится:
у нас используется doхygen - это тоже opensource, но работает неплохо. для c++ заточен лучше (во всяком случае для него он строит все возможные диаграммы - классов, вызовов и т.д.), а для c# хуже (т.е. практически никакие диаграммы не строит...)

[Sla]

ага
для php тоже не строит , по крайней мере, пробовал после твоего упоминания о doxygen

[Malaja]

понятно, плохо... Выговор doхygen-у с занесением

Хотя отсутствие результата - тоже результат, т.е. на эти грабли не будет наступать кто-то другой.
У нас в команде я была как раз тем, кто с этими граблями разбирался... Коллеги мне сначала, видимо, не совсем поверили, когда я их расстроила, и попробовали сами, решив, что для них лично doхygen таки построит схемки, но потом сознались в том, что и у них ничего не вышло.

Но сам хелп все равно создается, причем даже из стандартных комментариев (///), которые вносит автоматически студия (во всяком случае последняя версия doхygen-а этот коммент понимает)

[Malaja]

Вот, случайно наткнулась на следуюшее: в студии2003 в tools есть пункт "build Build Comment Web Pages" (фича называется, насколько я поняла "Code Comment Web Report"). В студии 2005 этой возможности уже нет...

[nikedeforest]

Использую Sandcastle сейчас. Тьфу-тьфу-тьфу, работает пока отлично. Но никаких диаграмм нет, только докметацияю. Делаю ввиде chm. Вид документации, как в МСДН.