Форум программистов «Весельчак У»
  *
Добро пожаловать, Гость. Пожалуйста, войдите или зарегистрируйтесь.
Вам не пришло письмо с кодом активации?

  • Рекомендуем проверить настройки временной зоны в вашем профиле (страница "Внешний вид форума", пункт "Часовой пояс:").
  • У нас больше нет рассылок. Если вам приходят письма от наших бывших рассылок mail.ru и subscribe.ru, то знайте, что это не мы рассылаем.
   Начало  
Наши сайты
Помощь Поиск Календарь Почта Войти Регистрация  
 
Страниц: [1]   Вниз
  Печать  
Автор Тема: XML-документация  (Прочитано 11498 раз)
0 Пользователей и 1 Гость смотрят эту тему.
nikedeforest
Команда клуба

ru
Offline Offline
Пол: Мужской

« : 21-05-2009 19:08 » 

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

ещё один вопрос ...
Sla
Команда клуба

ua
Offline Offline
Пол: Мужской

WWW
« Ответ #1 : 21-05-2009 19:34 » 

преобразовать его в XHTML Улыбаюсь
Записан

Мы все учились понемногу... Чему-нибудь и как-нибудь.
nikedeforest
Команда клуба

ru
Offline Offline
Пол: Мужской

« Ответ #2 : 21-05-2009 19:50 » 

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

ещё один вопрос ...
RXL
Технический
Администратор

ru
Offline Offline
Пол: Мужской

WWW
« Ответ #3 : 21-05-2009 19:51 » 

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

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

* xsl-test.zip (10.21 Кб - загружено 211 раз.)
Записан

... мы преодолеваем эту трудность без синтеза распределенных прототипов. (с) Жуков М.С.
Sla
Команда клуба

ua
Offline Offline
Пол: Мужской

WWW
« Ответ #4 : 21-05-2009 19:54 » 

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

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

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

Мы все учились понемногу... Чему-нибудь и как-нибудь.
Джон
просто
Администратор

de
Offline Offline
Пол: Мужской

« Ответ #5 : 21-05-2009 20:07 » 

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

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

Я вам что? Дурак? По выходным и праздникам на работе работать. По выходным и праздникам я работаю дома.
"Just because the language allows you to do something does not mean that it’s the correct thing to do." Trey Nash
"Physics is like sex: sure, it may give some practical results, but that's not why we do it." Richard P. Feynman
"All science is either physics or stamp collecting." Ernest Rutherford
"Wer will, findet Wege, wer nicht will, findet Gründe."
nikedeforest
Команда клуба

ru
Offline Offline
Пол: Мужской

« Ответ #6 : 22-05-2009 03:44 » 

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

ещё один вопрос ...
nikedeforest
Команда клуба

ru
Offline Offline
Пол: Мужской

« Ответ #7 : 22-05-2009 11:25 » 

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

ещё один вопрос ...
Алексей++
кот глобальный и пушистый
Глобальный модератор

ru
Offline Offline
Сообщений: 13


« Ответ #8 : 22-05-2009 12:46 » 

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

Dimka
Деятель
Команда клуба

ru
Offline Offline
Пол: Мужской

« Ответ #9 : 22-05-2009 13:38 » 

Алексей1153++, тебя это не касается, в 6-й студии такого нет Улыбаюсь
Записан

Программировать - значит понимать (К. Нюгард)
Невывернутое лучше, чем вправленное (М. Аврелий)
Многие готовы скорее умереть, чем подумать (Б. Рассел)
Алексей++
кот глобальный и пушистый
Глобальный модератор

ru
Offline Offline
Сообщений: 13


« Ответ #10 : 22-05-2009 13:43 » 

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

nikedeforest
Команда клуба

ru
Offline Offline
Пол: Мужской

« Ответ #11 : 25-05-2009 06:19 » 

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

ещё один вопрос ...
Dimka
Деятель
Команда клуба

ru
Offline Offline
Пол: Мужской

« Ответ #12 : 25-05-2009 09:35 » 

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

Программировать - значит понимать (К. Нюгард)
Невывернутое лучше, чем вправленное (М. Аврелий)
Многие готовы скорее умереть, чем подумать (Б. Рассел)
Джон
просто
Администратор

de
Offline Offline
Пол: Мужской

« Ответ #13 : 25-05-2009 10:27 » 

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

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

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

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

Я вам что? Дурак? По выходным и праздникам на работе работать. По выходным и праздникам я работаю дома.
"Just because the language allows you to do something does not mean that it’s the correct thing to do." Trey Nash
"Physics is like sex: sure, it may give some practical results, but that's not why we do it." Richard P. Feynman
"All science is either physics or stamp collecting." Ernest Rutherford
"Wer will, findet Wege, wer nicht will, findet Gründe."
nikedeforest
Команда клуба

ru
Offline Offline
Пол: Мужской

« Ответ #14 : 25-05-2009 10:55 » 

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

ещё один вопрос ...
Dimka
Деятель
Команда клуба

ru
Offline Offline
Пол: Мужской

« Ответ #15 : 25-05-2009 12:32 » 

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

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

Программировать - значит понимать (К. Нюгард)
Невывернутое лучше, чем вправленное (М. Аврелий)
Многие готовы скорее умереть, чем подумать (Б. Рассел)
nikedeforest
Команда клуба

ru
Offline Offline
Пол: Мужской

« Ответ #16 : 25-05-2009 13:44 » 

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

ещё один вопрос ...
Алексей++
кот глобальный и пушистый
Глобальный модератор

ru
Offline Offline
Сообщений: 13


« Ответ #17 : 25-05-2009 13:56 » 

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

Джон
просто
Администратор

de
Offline Offline
Пол: Мужской

« Ответ #18 : 25-05-2009 13:59 » 

Джон, я как раз твоего ответа и ждал. Улыбаюсь Че-то ...., разачарован немного Улыбаюсь.

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

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

Я вам что? Дурак? По выходным и праздникам на работе работать. По выходным и праздникам я работаю дома.
"Just because the language allows you to do something does not mean that it’s the correct thing to do." Trey Nash
"Physics is like sex: sure, it may give some practical results, but that's not why we do it." Richard P. Feynman
"All science is either physics or stamp collecting." Ernest Rutherford
"Wer will, findet Wege, wer nicht will, findet Gründe."
Dimka
Деятель
Команда клуба

ru
Offline Offline
Пол: Мужской

« Ответ #19 : 25-05-2009 15:30 » 

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

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

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

Программировать - значит понимать (К. Нюгард)
Невывернутое лучше, чем вправленное (М. Аврелий)
Многие готовы скорее умереть, чем подумать (Б. Рассел)
nikedeforest
Команда клуба

ru
Offline Offline
Пол: Мужской

« Ответ #20 : 25-05-2009 17:25 » 

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

ещё один вопрос ...
Malaja
Команда клуба

de
Offline Offline
Пол: Женский

« Ответ #21 : 12-11-2009 10:19 » 

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

холоднокровней, Маня, Ви не на работе
Sla
Команда клуба

ua
Offline Offline
Пол: Мужской

WWW
« Ответ #22 : 12-11-2009 12:30 » 

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

Мы все учились понемногу... Чему-нибудь и как-нибудь.
Malaja
Команда клуба

de
Offline Offline
Пол: Женский

« Ответ #23 : 12-11-2009 14:29 » 

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

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

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

холоднокровней, Маня, Ви не на работе
Malaja
Команда клуба

de
Offline Offline
Пол: Женский

« Ответ #24 : 12-11-2009 16:33 » 

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

холоднокровней, Маня, Ви не на работе
nikedeforest
Команда клуба

ru
Offline Offline
Пол: Мужской

« Ответ #25 : 29-12-2009 06:51 » 

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

ещё один вопрос ...
Страниц: [1]   Вверх
  Печать  
 

Powered by SMF 1.1.21 | SMF © 2015, Simple Machines