Создание help файла visual studio
Странно говорить о таких понятиях, как расширение функционала такого продукта, как Visual Studio в контексте «для чайников», но есть люди, которые и журналы смотрят с последней страницы. Эта статья для тех, кто уже имеет представление как обращаться со студией, но пока мало знает, чем она может помочь, и уже очень хочется добавить свою фичу.
Ожидаемые результаты
Научиться создавать и встраивать VSPackage расширения в VS 2012, на примере расширения для запуска калькулятора прямо из студии.
Что потребуется
Для разработки расширения потребуется сама студия, я воспользуюсь VS 2012, а также необходимо установить VS SDK 2012. Отмечу, что для разработки в VS 2010 есть VSPackage Builder , и этот инструмент помогает создавать расширения в дизайнере. Мы же обойдемся только шаблоном проекта предоставляемого SDK.
Шаг 1. Создаем проект
Файл->Создать->Проект->Шаблоны->Другие типы проектов-Расширение среды->Visual Studio Package и задаем имя проекта VSPackageCalc.
Шаг 2. Редактируем способ запуска и отображение кнопки в студии
Искомый файл: VSPackageCalc.vsct — файл с расширением .vsct
Определимся где отобразить кнопку и как запускать расширение, Отмечу два варианта отображения:
— добавление пункта меню в меню «Сервис»
— добавление панели кнопок в тулбар
Группа команд для меню «Сервис» задается так (код уже сгенерирован):
Как будет назваться панель инструментов в меню панелей инструментов (оставим имя по умолчанию VSPackageCalc Toolbar):
Честно говоря идентификаторов типа IDM_VS_MENU_TOOLS, указывающих в какой раздел меню можно поместить вызов функции расширения, много, и разбираться со всеми не входит в рамки статьи, но кое-что можно почерпнуть в MSDN
Далее определимся с видом кнопки тулбара. Сначала удалим лишнее кнопки из нашего тулбара (по умолчанию создаются инструменты для редактирования), заменив код с описанием группы кнопок тулбара расширения:
на код одного элемента тулбара:
Далее можно редактировать текст и отображения самого пункта меню:
Можно удалить элемент Icon (иконку), и тогда будет отображаться только текст. Иначе при отображении в тулбаре будет иконка, а чтобы показать и текст к ней, придется настраивать отдельно через инструмент настройки отображения кнопок тулбара в самой студии.
Шаг 3. Описание функционала расширения
Для задания функционала нашего расширения, его нужно описать в файле VSPackageCalcPackage.cs, отредактировав метод обработки нажатия на кнопку меню, который также был уже сгенерирован при создании проекта. Удалим все, что внутри метода и заменим на запуск приложения — стандартного калькулятора:
Шаг 4. Встраивание расширения
Ну вот почти и готово, осталось только собрать проект и в папке построения запустить VSPackageCalc.vsix.
После установки необходимо перезапустить студию.
Шаг 5. Использование встроенной фичи
Сначала нужно добавить панель инструментов VSPackageCalc Toolbar средствами VS — правая мышь по тулбару и отметить галочкой. Тула появилась на панели:
Заключение
Пусть фича не очень полезная и не сложная получилась, но, надеюсь, полученные знания подтолкнут к более глубокому изучению вопроса разработки расширений для Visual Studio.
Файл указаний содержит макрос, который в противном случае вызвал бы пропуск областей кода средством синтаксического анализа базы данных просмотра C++. При открытии проекта Visual Studio C++ система синтаксического анализа анализирует код в каждом исходном файле проекта и создает базу данных с информацией обо всех идентификаторах. Затем интегрированная среда разработки использует эту информацию для поддержки таких функций просмотра кода как обозреватель представления классов и панель навигации.
Средство синтаксического анализа базы данных просмотра C++ — это средство нечеткого синтаксического анализа, которое может анализировать большие объемы кода за короткий промежуток времени. Высокая скорость его работы объясняется в том числе и тем, что оно пропускает содержимое блоков. Например, оно записывает только расположение и параметры функции и игнорирует ее содержимое. Определенные макросы могут вызвать проблемы для эвристических правил, используемых для определения начала и конца блока. Эти проблемы приводят к тому, что области кода записываются неправильно.
Пропущенные области кода могут проявляться несколькими способами:
Отсутствуют типы и функции в представлении классов, в окне Перейти к и на панели навигации
Неправильные области на панели навигации
Предложения по Созданию объявления или определения функций, которые уже определены
Файл указаний содержит настраиваемые пользователем указания, которые имеют тот же синтаксис, что и определения макросов C/C++. В Visual C++ есть внутренний файл указаний, которого достаточно для большинства проектов. Однако вы можете создавать собственные файлы указаний, чтобы улучшить работу средства синтаксического анализа специально для вашего проекта.
При изменении или добавлении файла указаний необходимо выполнить дополнительные действия для того, чтобы изменения вступили в силу:
- В версиях до Visual Studio 2017 версии 15.6: удалите SDF-файл и(или) файл VC.db в решении для всех изменений.
- В Visual Studio 2017 версии 15.6 и более поздних версий: закройте и снова откройте решение после добавления новых файлов подсказки.
Сценарий
Без файла указаний Function не отображается в представлении классов, в окне Перейти к и на панели навигации. После добавления файла указаний с этим определением макроса средство синтаксического анализа может распознать и заменить макрос NOEXCEPT , что позволяет ему корректно проанализировать функцию:
Макросы, нарушающие работу
Существует две категории макросов, нарушающие работу средства синтаксического анализа:
Макросы, которые инкапсулируют ключевые слова, декорирующие функцию
Для следующих типов макросов в файле указаний необходимо указать только имя макроса:
Макросы, которые содержат несбалансированные скобки
Для следующих типов макросов в файле указаний необходимо указать имя макроса и его содержимое:
Поддержка редактора
Начиная с Visual Studio 2017 версии 15.8 существуют несколько функций, которые позволяют определить макросы, нарушающие работу средства синтаксического анализа:
Макросы, которые находятся внутри областей, пропущенных анализатором, выделяются.
Существует быстрое действие для создания файла указаний, включающего выделенный макрос, или (при наличии существующего файла указаний) для добавления макроса в файл указаний.
После выполнения любого из быстрых действий средство анализа повторно анализирует файлы, на которые повлиял файл указаний.
По умолчанию проблемный макрос выделяется как предложение. Выделение можно изменить на более заметное, например, подчеркивание красной или зеленой волнистой линией. Используйте параметр Макросы в пропущенных областях просмотра в разделе Подчеркивание кода, который можно открыть, выбрав Инструменты>Параметры>Текстовый редактор>C/C++>Представление.
Отображение ошибок базы данных просмотра
Команда меню "Ошибки базы данных" Project > Display отображает все регионы, которые не удалось проанализировать в списке ошибок. Команда призвана упростить создание начального файла указаний. Тем не менее, средство синтаксического анализа не может определить, был ли причиной ошибки макрос, нарушающий работу средства синтаксического анализа, поэтому вам необходимо оценить каждую ошибку самостоятельно. Выполните команду Показать ошибки базы данных просмотра и перейдите к каждой ошибке, чтобы загрузить соответствующий файл в редакторе. После загрузки файла все макросы, входящие в область, будут выделены. Вы можете вызвать быстрые действия, чтобы добавить их в файл указаний. После обновления файла указаний список ошибок обновляется автоматически. Кроме того, если вы изменяете файл указаний вручную, можно использовать команду Повторить сканирование решения, чтобы запустить обновление.
Архитектура
Файлы указаний относятся к физическим каталогам, а не к логическим каталогам, отображаемым в обозревателе решений. Чтобы файл указаний был применен, добавлять его в проект не нужно. Система анализа использует файлы указаний только при анализе исходных файлов.
Каждый файл указаний называется cpp.hint. Файлы указаний могут размещаться в различных каталогах, но в отдельном каталоге может находиться лишь один такой файл.
В проекте может использоваться как один или несколько файлов указаний, так и ни одного. При отсутствии файлов указаний система анализа использует методики восстановления после ошибок, чтобы пропускать нераспознаваемый исходный код. В противном случае система анализа использует указанную ниже стратегию для обнаружения и сбора указаний.
Порядок поиска
Система анализа ищет файлы указаний в каталогах в следующем порядке.
Каталог, содержащий пакет установки для Visual C++ (vcpackages). Этот каталог содержит встроенный файл указаний, описывающий символы в часто используемых системных файлах, таких как windows.h. Поэтому проект автоматически наследует основную часть нужных ему указаний.
Путь из корневого каталога исходного файла к каталогу, содержащему сам исходный файл. В типичном проекте Visual Studio C++ корневой каталог содержит файл проекта или решения.
Исключением из этого правила является ситуация, когда стоп-файл находится в пути к исходному файлу. Стоп-файл — это любой файл с именем cpp.stop. Стоп-файл обеспечивает дополнительный уровень контроля над порядком поиска. Вместо того чтобы начать с корневого каталога, система анализа выполняет поиск из каталога, содержащего стоп-файл, по направлению к каталогу, содержащему исходный файл. В обычных проектах стоп-файлы не требуются.
Сбор указаний
Система анализа открывает каждый файл указаний в указанном выше порядке поиска. Она собирает указания из каждого файла в набор полезных указаний, а затем использует эти полезные указания для интерпретации идентификаторов в коде.
Система анализа использует эти правила для сбора указаний:
Если новое указание задает имя, которое еще не было определено, новое указание добавляет имя в список полезных указаний.
Если новое указание задает уже определенное имя, существующее имя переопределяется.
Первое правило означает, что полезные указания наследуются от ранее открытых файлов указаний. Два последних правила означают, что более поздние указания в порядке поиска могут переопределять более ранние. Например, можно переопределить любые имеющиеся указания, создав файл указаний в каталоге с исходным файлом.
Описание сбора указаний см. в разделе Пример ниже.
Синтаксис
В указаниях используется следующий синтаксис:
Пример
В этом примере показано, как выполняется сбор указаний из соответствующих файлов. Стоп-файлы в этом примере не используются.
На рисунке показаны некоторые физические каталоги в проекте Visual Studio C++. Файлы указаний находятся в каталогах vcpackages , Debug , A1 и A2 .
Каталоги файлов указаний
Каталоги и содержимое файлов указаний
В списке ниже приведены каталоги в этом проекте, содержащие файлы указаний, и содержимое этих файлов. Приведены лишь некоторые из указаний в файле указаний каталога vcpackages :
Полезные указания
В следующей таблице приведены полезные указания для исходных файлов в этом проекте:
Исходный файл: A1_A2_B.cpp
Эти замечания применяются к предыдущему списку:
Эти полезные указания получены из каталогов vcpackages , Debug , A1 и A2 .
Файл указаний в каталоге A1 переопределяет START_NAMESPACE .
Установка Dr.Explain
Рисунок 1. Мастер установки «Dr.Explain»
Создание и настройка нового проекта
При запуске программы в окне «Проекты Dr.Explain» (Рисунок 2) выберите пункт «Создать новый проект» и нажмите «ОК», либо используйте пункт «Файл -> Создать» главного меню.
Рисунок 2. Окно «Проекты Dr.Explain»
Для настройки параметров экспорта в формат CHM, выберите пункт «Настройки -> Настройки проекта» в главном меню. Выберите раздел «CHM экспорт» в окне настроек.
Создание тематических разделов в файле справки
Создайте новую тему с помощью пункта «Настройки -> Добавить тему» главного меню. Также можно использовать пункт «Добавить -> Добавить тему» контекстного меню, которое вызывается нажатием правой кнопки мыши на любой позиции дерева проекта (Рисунок 3).
Рисунок 3. Дерево проекта «Dr.Explain»
Настройте порядок следования разделов в структуре документа с помощью пунктов «Выше» и «Ниже» контекстного меню. Изменить названия тем можно с помощью пункта «Переименовать».
Далее создайте содержимое разделов, выберите интересующий пункт в дереве проекта и приступайте к заполнению в окне редактора. Заполняйте раздел в свободной форме. В редакторе предусмотрены основные стандартные функции редактирования и форматирования текста и ряд функция для работы с изображениями, видео, таблицами и переменными. Использование переменных позволяет заменить повторяющиеся данные именем переменной. В таком случае при изменении присвоенного переменной значения, соответствующий текст изменится во всем документе.
Для повышения удобства поиска по файлу справки создайте и настройте ключевые слова. Откройте окно ключевых слов — кнопка «Ключевые слова» (Рисунок 4). Для добавления и удаления слов служат одноименные кнопки. Настройте привязку тем к словам, для этого выбрав интересующий раздел в структуре проекта, проставьте метки в полях тех терминов, которые хотите ассоциировать с данной темой.
Рисунок 4. Ключевые слова
Рисунок 5. Окно «Захват объекта»
После открытия окна «Захват объекта» (Рисунок 5) установите метки в поле «Accessible -объект» или «Win 32-окно», затем выполните захват изображения интересующей формы одним из способов, предложенных в окне захвата. В структуре документа будет автоматически создан раздел, содержащий аннотированное изображение формы приложения (Рисунок 6). В окне редактора можно добавить и удалить аннотацию или изменить порядок следования описания отдельных элементов.
Рисунок 6. Результат выполнения захвата объекта
Настройка значений Help ID
Рисунок 7. Изменение значения Help ID в окне «Свойства страницы»
Предварительный просмотр и сохранение проекта
Перед экспортом проекта используйте функцию предварительного просмотра — кнопка «Просмотр CHM», чтобы убедиться в корректном отображении всех разделов справки. Если необходимо внести изменения, вернитесь в режим редактирования.
Для сохранения проекта выберите пункт «Файл -> Сохранить как» главного меню, введите имя файла и укажите путь его размещения в открывшемся окне сохранения.
Экспорт проекта в CHM-файл
Рисунок 8. Окно «Экспорт в CHM»
- откройте проект с помощью средств среды разработки, которую вы используете;
- в редакторе форм (Рисунок 9) выберите «Button» из панели элементов;
- поместите элемент в форму;
- в свойствах элемента задайте название и подпись кнопки, например, например, «HlpButton» и «Help». Параметры вводятся в поля «Name» и «Text» соответственно;
Рисунок 9. Редактор форм среды разработки Microsoft Visual Studio
Рисунок 10. Редактор кода среды разработки Microsoft Visual Studio
При таком способе вызова файла справки при любых его перемещениях необходимо заново указывать в коде полный путь.
Будьте внимательны, для обеспечения правильной работы элемента вызова файла справки строго соблюдайте синтаксис, приведенный в примерах.
- добавьте компонент «Help Provider» путем егоперемещения в форму приложения из панели элементов. Значок компонента появится в нижней части окна редактора форм;
ОБРАТИТЕ ВНИМАНИЕ: Допускается использование нескольких компонентов «Help Provider». Это удобно в том случае, когда информация о различных элементах содержится в различных файлах справки. Также вы можете использовать отдельные компоненты для различных форм;
- в окне свойств элемента «Help Provider» укажите расположение файла справки — поле «HelpNamespace»
ОБРАТИТЕ ВНИМАНИЕ: Если файл справки располагается в одной папке с исполнительным файлом приложения, то достаточно указать только имя файла. При раздельного размещении файлов необходимо указать полный путь. В таком случае при любом перемещении файла справки, значение параметра «HelpNamespace» должно быть заменено актуальным.
- в окне свойств объекта внесите значение Help ID соответствующего объекту раздела справки в поле «HelpKeyword on Help Provider1». Выберите значение «TopicId» для поля «Help Navigator on Help Provider1»
ОБРАТИТЕ ВНИМАНИЕ: Количество параметров «HelpKeyword …» и «Help Provider…» в свойствах объектов соответствует количеству используемых компонентов «Help Provider», а цифра в наименовании параметра соответствует номеру компонента. Будьте внимательны при заполнении данных полей;
- убедитесь в правильной работе компонента «Help Provider». Запустите отладку — пункт «Debug -> Start debugging» главного меню, после чего на экране появится стартовая форма приложения. При нажатии клавиши «F1» должен открыться тот раздел файла справки, который соответствует элементу, находящемуся в фокусе;
- повторите описанную процедуру для всех объектов, которые необходимо ассоциировать с определенными разделами файла справки.
Открытие определенных разделов файла справки с помощью компонента Help Provider
Помимо вызова определенных разделов файла справки по соответствующим им HelpID, компонент «HelpProvider» также может быть использован для адресации разделов с использованием других параметров. Для настройки вызова определенных разделов необходимо установить соответствующие значения полей «HelpKeyword on Help Provider1» и «Help Navigator on Help Provider1» в свойствах элементов. Для настройки вывода определенных разделов файла справки при нажатии клавиши «F1» проделайте следующие действия:
- добавьте компонент «Help Provider», перетащите его из панели элементоввформу. Компонент отобразится в нижней части окна редактора форм;
- укажите расположение файла справки — поле «HelpNamespace» в окне свойств объекта «Help Provider»;
- в окне свойств элемента, в поле «HelpNavigator on Help Provider1» выберите интересующий параметр:
·AssociateIndex— открывает вкладку «Указатель» иподсвечивает в списке первое по порядку ключевое слово, название которого начинается с сочетания символов в поле «HelpKeyword on Help Provider1»;
·Index — открывает вкладку «Указатель» и подсвечивает в спискеключевое слово, указанное в поле «HelpKeyword on Help Provider1»;
·Find — открывает вкладку «Поиск»;
·TableOfContents — открывает оглавление;
·Topic — открывает раздел, название которого указано в поле «HelpKeyword on Help Provider1».
ОБРАТИТЕ ВНИМАНИЕ: Название раздела указывается в формате «Topic.htm», это необходимо для правильной работы вызова справки.
·TopicId — открываетраздел,которому соответствует параметр Help ID, указанный в поле «HelpKeyword on Help Provider1»;
·KeywordIndex — открывает вкладку «Указатель» и выводит список разделов, содержащих ключевое слово, указанное в поле «HelpKeyword on Help Provider1».
Такой способ вызова справки позволяет гибко настроить адресацию и поиск в справочной системе, а также использовать для каждой отдельной формы или элемента соответствующий им файл справки или отдельные его разделы.
Если необходимо вызвать определенный раздел справочной системы с помощью кнопки, используйте следующие фрагменты кода:
Код вызова стартовой страницы справки:
Код вызова вкладки «Указатель»:
Код вызова оглавления:
Код вызова вкладки «Поиск»:
Код вызова поиска по первым буквам ключевого слова:
где me — сочетание букв для поиска
Код вызова поиска по ключевому слову:
где FAQ — ключевое слово
Код вызова раздела по его названию:
где Overview.htm — название раздела (ключевое слово всегда указывается в формате Topic.htm)
Статья посвящена созданию файла справки в программе Dr.Explain и его интеграции в приложение Visual Basic. Основные рассматриваемые вопросы:
- создание и настройка проекта в Dr.Explain;
- создание удобной структуры файла справки;
- создание аннотированного изображения формы интерфейса приложения Visual Basic;
- настройка значений Help ID;
- сохранение проекта;
- экспорт проекта в СHM файл;
- интеграция файла справки в приложение Visual Basic.
Установка Dr.Explain
Функционал пробной и полной версий идентичен. Единственное отличие – при использовании пробной версии все изображения в экспортированных файлах помечаются водяными знаками.
Рисунок 1. Мастер установки «Dr.Explain»
Создание и настройка нового проекта
Выберите пункт «Создать новый проект» в окне «Проекты Dr.Explain» (Рисунок 2) и нажмите «ОК», либо воспользуйтесь пунктом «Создать» в меню «Файл».
Рисунок 2. Окно «Проекты Dr.Explain»
Настройте параметры экспорта в формат CHM. Для этого в главном меню выберите пункт «Настройки -> Настройки проекта» ив открывшемся окне перейдите в раздел «CHM экспорт».
Создание тематических разделов в файле справки
Создание отдельных тематических разделов для описания различных элементов приложения Visual Basic позволит получить удобную структуру файла справки.
Для создания новой темы используйте пункт «Настройки -> Добавить тему» главного меню. Либо вызовите контекстное меню нажатием правой кнопки мыши по любой из позиций дерева проекта (Рисунок 3) и выберите пункт «Добавить -> Добавить тему». Создайте тематические разделы для всех форм и элементов приложения.
Рисунок 3. Дерево проекта «Dr.Explain»
С помощью пунктов «Переименовать», «Выше» и «Ниже» контекстного меню вы можете переименовать темы и изменить порядок их следования в структуре документа. Для заполнения разделов выберите интересующий пункт в дереве проекта – его содержимое отобразится в окне редактора. Заполните раздел необходимой текстовой и графической информацией. Редактор содержит стандартный набор основных функций работы с текстом.
Также в редакторе предусмотрен ряд функций для работы с изображениями, видео, таблицами и переменными (использование переменных позволяет заменить повторяющиеся данные именем переменной. В таком случае при изменении присвоенного переменной значения, соответствующий текст изменится во всем документе).
Создание ключевых слов повысит удобство поиска по файлу справки. Для добавления и удаления слов служат соответствующие кнопки в панели «Ключевые слова» (Рисунок 4), которая вызывается нажатием одноименной кнопки. Чтобы изменить привязку тем к словам, выберите интересующий раздел в дереве проекта и установите метки напротив слов, с которыми необходимо его ассоциировать.
Рисунок 4. Ключевые слова
Функция «Захват объекта» (Рисунок 5), которая вызывается кнопкой «Схватить экран», позволяет создать наглядное описание форм интерфейса и отдельных элементов приложения Visual Basic.
Рисунок 5. Окно «Захват объекта»
Выберите поле «Accessible-объект» или «Win32-окно» в окне захвата, после чего перейдите к приложению Visual Basic и захватите изображение интересующей формы одним из способов, предложенных в окне захвата. Тема, содержащая аннотированное изображение интерфейса, будет автоматически создана и добавлена в структуру документа (Рисунок 6). В окне редактора можно добавить и удалить аннотацию или изменить порядок следования описания отдельных элементов.
Рисунок 6. Результат выполнения захвата объекта
Настройка значений Help ID
Для последующей привязки тем файла справки к элементам приложения в программе Dr.Explain предусмотрена возможность редактирования значений HelpID. Выберите в дереве проекта интересующую тему и нажмите на ячейку «HelpID» в окне свойств страницы (Рисунок 7). Введите требуемое значение и уберите фокус мыши с поля, чтобы сохранить настройки.
Рисунок 7. Изменение значения Help ID в окне «Свойства страницы»
Предварительный просмотр и сохранение проекта
После завершения работы над проектом воспользуйтесь функцией предварительного просмотра — кнопка «Просмотр CHM». Убедитесь в корректном отображении созданного документа и всех его разделов. Для внесения необходимых изменений вернитесь в режим редактирования.
Сохраните проект — выберите пункт «Файл -> Сохранить как» главного меню, в открывшемся окне сохранения введите имя файла и укажите его размещение.
Экспорт проекта в CHM-файл
Рисунок 8. Окно «Экспорт в CHM»
Интеграция CHM-файла в приложение Visual Basic
Для вызова справки в приложении Visual Basic необходимо создать соответствующий элемент управления, например, кнопку.
Для создания элемента управления выполните следующие действия:
- откройте ваш проект с помощью средств среды разработки, которую вы используете;
- перейдите в редактор форм (Рисунок 9);
- в панели элементов выберите «Button»;
- разместите кнопку в форме;
- в области свойств измените название элемента и его подпись. Название вводится в поле «(Name)», а подпись в поле «Text» - введите интересующие значения, например, «HlpButton» и «Help» соответственно;
- перейдите в редактор кода элемента (Рисунок 10).
Рисунок 9. Редактор форм среды разработки Microsoft Visual Studio
Рисунок 10. Редактор кода среды разработки Microsoft Visual Studio
Private Sub HlpButton_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles HlpButton.Click
Call Shell("explorer.exe" & My.Application.Info.DirectoryPath + "\help.chm", vbNormalFocus)
End Sub
- проверьте корректную работу элемента управления. Для этого выберите пункт «Debug -> Start debugging» главного меню, после чего на экране появится стартовая форма приложения. При нажатии кнопки «Help» должен открыться файл справки, созданный ранее в программе Dr.Explain;
- повторите описанную процедуру для всех форм, в которые необходимо вставить элемент вызова справки.
Private Sub HlpButton_Click(ByVal sender As System.Object, ByVal e AsSystem.EventArgs) Handles HlpButton.Click
Shell("cmd /cstart D:\work\techwrite\help.chm")
End Sub
В таком случае, при любом изменении размещения файла справки, путь, указываемый в коде элемента управления, должен быть заменен на актуальный.
Будьте внимательны при вводе кодов управляющих элементов, строго соблюдайте синтаксис, приведенный в примерах – это является обязательным условием правильной работы элемента вызова файла справки.
Привязка темы файла справки CHM к объектам приложения Visual Basic
Вы можете настроить свойства элементов управления в приложении Visual Basic таким образом, что при нажатии клавиши «F1» будет открываться раздел файла справки, соответствующий объекту, на котором в настоящее время находится фокус:
- чтобы добавить компонент «HelpProvider», перетащите его из панели элементов в форму. Компонент отобразится в нижней части окна редактора форм;
ОБРАТИТЕ ВНИМАНИЕ! Вы можете использовать несколько компонентов «HelpProvider», например, по одному для каждой формы, или в случае, если информация о различных объектах хранится в различных файлах справки.
- укажите расположение файла справки — поле «HelpNamespace» в окне свойств объекта «HelpProvider»;
ОБРАТИТЕ ВНИМАНИЕ! Вы можете указать только имя файла справки. В таком случае необходимо, чтобы он располагался в одной папке с исполнительным файлом приложения. Полный путь должен быть указан в случае раздельного размещения файлов, тогда при любом изменении места нахождения файла справки, значение параметра «HelpNamespace» должно быть заменено актуальным.
- выберите интересующий объект, перейдите в окно свойств и внесите значение Help ID соответствующего объекту раздела файла справки в поле «HelpKeywordon Help Provider1». В поле «HelpNavigator on Help Provider1» выберите значение «TopicId»;
ОБРАТИТЕ ВНИМАНИЕ! Количество параметров«HelpKeyword…» и «HelpProvider…» в свойствах объектов соответствует количеству используемых компонентов«HelpProvider», ацифра в наименовании параметра соответствует номеру компонента. Будьте внимательны при заполнении данных полей.
- проверьте корректную работу компонента «HelpProvider». Для этого выберите пункт «Debug -> Start debugging» главного меню, после чего на экране появится стартовая форма приложения. При нажатии клавиши «F1» должен открыться тот раздел файла справки, который соответствует элементу, находящемуся в фокусе;
- повторите описанную процедуру для всех объектов, которые необходимо ассоциировать с определенными разделами файла справки.
Открытие определенных разделов файла справки с помощью компонента Help Provider
Помимо вызова определенных разделов файла справки по соответствующим им HelpID, компонент «HelpProvider» также может быть использован для адресации разделов с использованием других параметров. Для настройки вызова определенных разделов необходимо установить соответствующие значения полей «HelpKeyword on Help Provider1» и «HelpNavigator on Help Provider1» в свойствах элементов. Для настройки вывода определенных разделов файла справки при нажатии клавиши «F1» проделайте следующие действия:
- добавьте компонент «HelpProvider», перетащите его из панели элементоввформу. Компонент отобразится в нижней части окна редактора форм;
- укажите расположение файла справки — поле «HelpNamespace» в окне свойств объекта «HelpProvider»;
- В окне свойств элемента, в поле «HelpNavigator on Help Provider1» выберите интересующий параметр:
· AssociateIndex— открывает вкладку «Указатель» иподсвечивает в списке первое по порядку ключевое слово, название которого начинается с сочетания символов в поле «HelpKeywordon Help Provider1»
· Index — открывает вкладку «Указатель» и подсвечивает в спискеключевое слово, указанное в поле «HelpKeywordon Help Provider1»
· Find — открывает вкладку «Поиск»
· TableOfContents — открывает оглавление
· Topic — открывает раздел, название которого указано в поле «HelpKeyword on Help Provider1».
ОБРАТИТЕ ВНИМАНИЕ! название раздела указывается в формате «Topic.htm», это необходимо для правильной работы вызова справки;
· TopicId — открываетраздел,которому соответствует параметр HelpID, указанный в поле «HelpKeyword on Help Provider1»
· KeywordIndex — открывает вкладку «Указатель» и выводит список разделов, содержащих ключевое слово, указанное в поле «HelpKeyword on Help Provider1».
Такой способ вызова справки позволяет гибко настроить адресацию и поиск в справочной системе, а также использовать для каждой отдельной формы или элемента соответствующий им файл справки или отдельные его разделы.
Если необходимо вызвать определенный раздел справочной системы с помощью кнопки, используйте следующие фрагменты кода:
Код элемента вызова стартовой страницы справки:
Public Class Form1
Inherits System.Windows.Forms.Form
Private helpfile As String = "help.chm"
Private Sub HlpButton_Click(sender As System.Object, e As System.EventArgs) Handles HlpButton.Click
Help.ShowHelp(Me, helpfile)
End Sub
Код элемента вызова вкладки «Указатель»:
Public Class Form1
Inherits System.Windows.Forms.Form
Private helpfile As String = "help.chm"
Private Sub HlpButton_Click(sender As System.Object, e As System.EventArgs) Handles HlpButton.Click
Help.ShowHelpIndex(Me, helpfile)
End Sub
Код элемента вызова оглавления
Public Class Form1
Inherits System.Windows.Forms.Form
Private helpfile As String = "help.chm"
Private Sub HlpButton_Click(sender As System.Object, e As System.EventArgs) Handles HlpButton.Click
Dim navigator As HelpNavigator = HelpNavigator.TableOfContents
Help.ShowHelp(Me, helpfile)
EndSub
Код элемента вызова вкладки «Поиск»:
Public Class Form1
Inherits System.Windows.Forms.Form
Private helpfile As String = "help.chm"
Private findtext As String = ""
Private Sub HlpButton_Click(sender As System.Object, e As System.EventArgs) Handles HlpButton.Click
Dim navigator As HelpNavigator = HelpNavigator.Find
Help.ShowHelp(Me, helpfile, navigator, findtext)
EndSub
Код элемента вызова поиска по первым буквам ключевого слова:
Public Class Form1
Inherits System.Windows.Forms.Form
Private helpfile As String = "help.chm"
Private AsIndex As String = "me"
Private Sub HlpButton_Click(sender As System.Object, e As System.EventArgs) Handles HlpButton.Click
Dim navigator As HelpNavigator = HelpNavigator.AssociateIndex
Help.ShowHelp(Me, helpfile, navigator, AsIndex)
EndSub
где "me"— сочетание букв для поиска.
Код элемента вызова поиска по ключевому слову:
Public Class Form1
Inherits System.Windows.Forms.Form
Private helpfile As String = "help.chm"
Private Index As String = "FAQ"
Private Sub HlpButton_Click(sender As System.Object, e As System.EventArgs) Handles HlpButton.Click
Dim navigator As HelpNavigator = HelpNavigator.Index
Help.ShowHelp(Me, helpfile, navigator, Index)
EndSub
где "FAQ" — ключевое слово
Код элемента вызова раздела по его названию:
Public Class Form1
Inherits System.Windows.Forms.Form
Private helpfile As String = "help.chm"
Private Topic As String = "Overview.htm"
Private Sub HlpButton_Click(sender As System.Object, e As System.EventArgs) Handles HlpButton.Click
Dim navigator As HelpNavigator = HelpNavigator.Topic
Help.ShowHelp(Me, helpfile, navigator, Topic)
EndSub
где "Overview.htm"— название раздела (ключевое слово всегда указывается в формате Topic.htm)
Код элемента вызова раздела по его HelpID:
Public Class Form1
Inherits System.Windows.Forms.Form
Private helpfile As String = "help.chm"
Private TopicId As String = "1500"
Private Sub HlpButton_Click(sender As System.Object, e As System.EventArgs) Handles HlpButton.Click
Dim navigator As HelpNavigator = HelpNavigator.TopicId
Help.ShowHelp(Me, helpfile, navigator, TopicId)
EndSub
где "1500" — значение HelpID интересующего раздела
Код вызова списка разделов, содержащих ключевое слово:
Public Class Form1
Inherits System.Windows.Forms.Form
Private helpfile As String = "help.chm"
Private KeywInd As String = "menu"
Private Sub HlpButton_Click(sender As System.Object, e As System.EventArgs) Handles HlpButton.Click
Dim navigator As HelpNavigator = HelpNavigator.KeywordIndex
Help.ShowHelp(Me, helpfile, navigator, KeywordIndex)
EndSub
Есть разные подходы к написанию документации. Некоторые команды предпочитают начинать создание документации в момент начала создания продукта. Другие откладывают написание мануалов на окончание работ. В некоторых командах документацию пишут специальные люди, которые ходят от разработчика к разработчику и от менеджера к менеджеру, аккумулируя знания о продукте. Во многих небольших командах таких специальных людей нет, а потому документацию часто пишет разработчик или разработчики. Кто-то использует сторонние средства вроде Help & Manual, в которых, как в заправском текстовом редакторе, можно создавать очень сложную верстку и на выходе получать документацию в многообразии форматов. Многие используют другой подход, широко пропагандируемый в последнее время – написание документации прямо в коде программы/библиотеки.
Я в своей работе использовал и сторонние средства, и встроенные. Начинал писать документацию и сразу, и в последний момент. В итоге я для себя решил, что документацию лучше начинать писать во второй половине создания продукта, так как чем ближе к завершению, тем более стабилен API, набор возможностей и т.п., а значит, реже придется корректировать документацию. Написание документации прямо в коде тоже, в конечном счете, оказалось удобнее, чем в сторонних программах, хотя поначалу казалось совсем наоборот. Эта статья как раз о том, как писать документацию прямо в коде.
Описываем API
По умолчанию создание xml-файла из комментариев отключено. Его нужно включить в свойствах проекта на вкладке Build.
В результате при компиляции, в дополнение к файлу вашей сборки, будет сгенерирован xml-файл, который содержит все xml-комментарии из кода (в том числе комментарии к непубличным структурам). Этот файл уже сам по себе полезен тем, что если его положить рядом со сборкой (вашей dll), то это позволит функции IntelliSense в Visual Studio отображать описания для методов в момент набора пользователем кода. Вот пример того, как это будет выглядеть для функции GetR, показанной выше:
Однако в большинстве случаев сгенерированный xml-файл содержит комментарии к внутренним структурам, которые пользователям не нужно или нельзя видеть. Ниже я напишу, как автоматически очистить xml-файл так, чтобы в нем остались только описания к публичным методам.
Я не буду подробно рассматривать все xml-теги, а лишь попробую кратко описать наиболее часто используемые.
Тег summary служит для краткого описания назначения класса, интерфейса, перечисления (enum), методов и свойств класса или интерфейса и членов перечисления. Тег param позволяет описать параметр, принимаемый функцией. Этот тег нужно использовать для каждого принимаемого параметра. Тег returns используется для описания возвращаемого значения функции. Тег value полезен для описания значения, которое принимает и/или возвращает некоторое свойство. В некотором смысле тег value является аналогом тега returns.
///
/// Gets the font ascent.
///
///The font ascent.
///Ascent is the maximum height above the baseline reached
/// by glyphs in this font, excluding the height of glyphs for
/// accented characters.
public short Ascent
<
get
<
return Impl. Ascent ;
>
>
Очень полезным (и, к сожалению, часто игнорируемым) является тег remarks, который позволяет указать примечания к описываемой сущности. Этот тег можно использовать практически везде кроме описания членов перечисления. На самом деле для членов перечисления тоже можно, но в документации, оформленной в стиле vs2005, этих примечаний просто не будет видно, что уменьшает полезность таких примечаний.
Приведу еще несколько практических замечаний/рекомендаций.
Скачайте и установите расширение для Visual Studio под названием GhostDoc. Это расширение работает во всех версия студии (начиная с версии 2005) и сильно упрощает создание xml комментариев. По нажатию на Ctrl-Shift-D это расширение вставляет описание сущности, на которой в данный момент стоит курсор. Вставляются все необходимые теги, и генерируется текст описания на основе, например, названия метода и названия его параметров. Часто остается лишь откорректировать и дополнить сгенерированный текст.
Недостаток написания документации прямо в коде в том, что комментариев порой больше, чем кода, что может сильно затруднять чтение кода. Для обхода этой проблемы очень удобным оказывается полное разделение публичного интерфейса и реализации.
Если у вас есть несколько перегруженных методов, то при генерации документации для них будет создана отдельная страница (вот пример такой страницы). Текст для этой страницы нужно указать в теге overloads в описании одного из перегруженных методов.
///
/// Saves the font bytes to the specified stream.
///
/// The stream to save font bytes to.
///Saves the font bytes to a file or a stream.
public void Save ( Stream stream )
<
Impl. Save ( stream ) ;
>
Если вы хотите в описании одного метода дать ссылку на другой метод или тип, то нужно использовать конструкцию вида
Пример использования частичной спецификации (PdfFontEmbedStyle находится в одном пространстве имен с PdfFont):
public sealed class PdfFont
<
…
///
/// Gets or sets the value that specifies
/// how this font is embedded into the document.
///
///The value that specifies
/// how this font is embedded into the document.
public PdfFontEmbedStyle EmbedStyle
<
get
<
return Impl. EmbedStyle ;
>
set
<
Impl. EmbedStyle = value ;
>
>
>
- ссылка на свойство
- ссылка на метод
- ссылка на группу перегруженных методов
- ссылка на класс
Со ссылками на группу перегруженных методов связана одна неприятность. Visual Studio требует, чтобы такие ссылки были вида O:XXX.YYY , в то время как Sandcastle Help File Builder требует, чтобы такие ссылки были вида Overload:XXX.YYY . Для решения этой проблемы я использую простой скрипт, который вызывается на Post-build event и заменяет в xml-файле O: на Overload: , что вполне терпимо.
Генерируем файл документации
- секция Build: FrameworkVersion
- секции Help File: CopyrightHref, CopyrightText, FeedbackEMailAddress, FeedbackEMailLinkText, HelpTitle, HtmlHelpName
- секция Paths: OutputPath
Еще один важный шаг – описать пространства имен (namespace-ы) в SHFB. Xml комментарии в коде не работают для namespace-ов, поэтому нужно это сделать вручную. Тут поможет секция Comments и свойство NamespaceSummaries в ней. В описании namespace-ов можно использовать стандартные html теги.
Настройка проекта завершена, пришло время построить сhm-файл. Выбираем Documentation->Build Project, и, если все было сделано правильно, то получаем красивый файл документации в стиле MSDN.
Пишем статьи
Однако не стоит останавливаться на достигнутом – одного описания API вашего компонента не достаточно для полноценной документации. Хорошая документация обычно содержит дополнительные статьи, примеры, FAQ и т.п.
В окне Project Explorer добавляем новый элемент Content Layout – это описание (с указанием взаиморасположения) того, что входит в документацию. В окне Content Layout добавляются новые статьи (topics). Каждая статья описывается в MAML формате (.aml файлы), это xml-based формат. Sandcastle Help File Builder поставляется с набором предопределенных шаблонов, что значительно упрощает дебют в написании статей. Я в основном использую шаблон Conceptual, реже – Walkthrough.
Описание каждой статьи начинается с указания topic id – уникального идентификатора. На основе этого идентификатора генерируется html файл, который позже попадет в chm. Генерируемый html-файл именуется в форме “TOPIC_ID.htm”. Данный topic id используется также для ссылок на статью из других статей или xml-комментариев в коде.
При создании статьи предлагается ее сохранить в файл с именем “TOPIC_ID.aml”. Можно и нужно при создании сразу указать нормальное имя для файла.
Рассмотрим некоторые элементы управления в SHFB, которые полезны при редактировании статей.
Устанавливает стартовую страницу документации (будет показываться при открытии документации. | |
Устанавливает положение, в которое будет вставлено описание API, сгенерированное из xml-файла. В зависимости от того, какой вариант выбран, описание API будет вставлено либо перед, либо после, либо как дочерний элемент помеченного таким образом элемента. | |
Предварительный просмотр текущей статьи. | |
Вставка ссылки на статью в документации. Используйте topic id в качестве адреса. | |
Вставка стандартных тегов для разметки статьи. |
Окно Entity Reference (на картинке расположено справа) можно использовать для вставки ссылок на описание функций/методов и т.п. сущностей из кода. Такой способ вставки ссылок не очень удобен на мой взгляд, так как нужно сначала открыть текст статьи, потом открыть окно Entity Reference, потом в этом окне написать часть или полное названия сущности, потом найти в списке нужную строку и дважды кликнуть на нее. Все это приведет к тому, что в статью вставится ссылка в позиции курсора. Я предпочитаю писать ссылки руками, а текст для ссылок находить в build log-е (лог от предыдущего билда можно открыть в текстовом редакторе).
Для вставки кода в статью используется тег . Например:
- В окне Project Explorer выбираем Add, потом Existing Item и выбираем нужную картинку.
- В свойствах добавленного файла меняем BuildAction на Image, а свойство ImageId – на удобное название (будет использоваться в ссылках на это изображение).
К сожалению, в текущей версии SHFB редактор далек от совершенства. Например, теги не закрываются автоматически, очень много действий приходится делать мышью (нет хоткеев), не для всех стандартных тегов есть соответствующие элементы на тулбаре. Парадоксально, но мне для большинства действий с aml-файлами удобнее использовать Visual Studio. Разумеется, можно использовать и любой другой удобный xml-редактор для написания статей.
Интеграция в процесс сборки
Можно включить файл проекта (*.shfbproj) от Sandcastle Help File Builder в solution Visual Studio, однако в настоящее время нет возможности использовать его как полноценный проект. То есть вы не сможете увидеть содержимое такого проекта, проект лишь добавится в группу Solution Items.
- Для solution выбираете Add->Existing Item…, добавляете проект документации. Будет добавлен в папку Solution Items.
- Щелкаете по добавленному элементу правой кнопкой мыши и выбираете Open With… В открывшемся диалоге добавляете ”Sandcastle Help File Builder GUI” и устанавливаете его в качестве редактора по умолчанию.
Более полезна сборка документации из командной строки. Такую сборку можно делать на Post-Build event или в других случаях. Собрать документацию из командной строки очень просто следующей командой:
%SystemRoot%\Microsoft.NET\Framework\v3.5\MSBuild.exe" /p:Configuration=Release Help.shfbproj
В этой строке Help.shfbproj – название проекта документации.
Надеюсь, эта статья поможет вам начать писать документацию к вашим проектам (если вы еще этого не делаете) за что ваши пользователи наверняка скажут вам спасибо. Успехов вам в написании документации!
Читайте также: