Как описать возможности программы

Текст раздела Описание применения должен состоять из следующих подразделов:

входные и выходные данные.

В зависимости от особенностей программы допускается вводить дополнительные разделы или объединять отдельные подразделы.

В подразделе “Назначение программы” указывают назначение, возможности программы, ее основные характеристики, ограничения, накладываемые на область применения программы.

В подразделе “Условия применения” указывают условия, необходимые для выполнения программы (требования к необходимым для данной программы техническим средствам, и другим программам, общие характеристики входной и выходной информации, а также требования и условия организационного, технического и технологического характера и т.п.).

В подразделе “Описание задачи” должны быть указаны определения задачи и методы ее решения.

В подразделе “Входные и выходные данные” должны быть указаны сведения о входных и выходных данных.

Руководство системного программиста

Текст раздела Руководство системного программиста должен содержать следующие подразделы:

Возможности программы ADT. Описание на русском.

общие сведения о программе;

сообщения системному программисту.

В зависимости от особенностей программы допускается объединять отдельные подразделы или вводить новые.

В обоснованных случаях допускается подраздел “Дополнительные возможности” не приводить, а в наименованиях подразделов опускать слово “программа” или заменять его на “наименование программы”.

В подразделе “Общие сведения о программе” должны быть указаны назначение и функции программы и сведения о технических и программных средствах, обеспечивающих выполнение данной программы.

В подразделе “Структура программы” должны быть приведены сведения о структуре программы, ее составных частях, о связях между составными частями и о связях с другими программами.

В подразделе “Настройка программы” должно быть приведено описание действий по настройке программы на условия конкретного применения (настройка на состав технических средств, выбор функций и др.). При необходимости приводят поясняющие примеры.

В подразделе “Проверка программы” должно быть приведено описание способов проверки, позволяющих дать общее заключение о работоспособности программы (контрольные примеры, методы прогона, результаты).

В подразделе “Дополнительные возможности” должно быть приведено описание дополнительных разделов функциональных возможностей программы и способов их выбора.

В подразделе “Сообщения системному программисту” должны быть указаны тексты сообщений, выдаваемых в ходе выполнения настройки, проверки программы, а также в ходе выполнения программы, описание их содержания и действий, которые необходимо предпринять по этим сообщениям.

В разделе к руководству системного программиста могут быть приведены дополнительные материалы (примеры, иллюстрации, таблицы, графики и т.п.).

Руководство программиста

Раздел Руководство программиста должен содержать следующие подразделы:

назначение и условия применения программы;

входные и выходные данные;

В зависимости от особенностей ПЗ допускается объединять отдельные разделы или вводить новые.

В подразделе “Назначение и условия применение программы” должны быть указаны назначение и функции, выполняемые программой, условия, необходимые для выполнения программы (объем оперативной памяти, требования к составу и параметрам периферийных устройств, требованию к программному обеспечению и т.п.).

В подразделе “Обращение к программе” должно быть приведено описание процедур вызова программы (способы передачи управления и параметров данных и др.).

В подразделе “Входные и выходные данные” должно быть приведено описание организации используемой входной и выходной информации и, при необходимости ее кодирования.

В подразделе “Сообщения” должны быть указаны тексты сообщений, выдаваемых программисту или оператору в ходе выполнения программы, описание их содержания и действия, которые необходимо принять по этим сообщениям.

В разделе к руководству программиста могут быть приведены дополнительные материалы (примеры, иллюстрации, таблицы, графики и т.п.).

Источник: studfile.net

Создание документации в .NET

Качественная документация – неотъемлемая часть успешного программного продукта. Создание полного и понятного описания всех функций и возможностей программы и программного компонента требует немало сил и терпения. В данной статье я рассмотрю некоторые практические аспекты создания документации для .NET компонентов.

Предположим, что у нас готова или почти готова некоторая .NET библиотека для разработчиков (они же конечные пользователи). API библиотеки безупречен, количество багов впечатляюще мало, да и вообще это не библиотека, а просто кладезь совершенного кода. Дело за малым – объяснить пользователям, как работать с этим замечательным продуктом.

Есть разные подходы к написанию документации. Некоторые команды предпочитают начинать создание документации в момент начала создания продукта. Другие откладывают написание мануалов на окончание работ. В некоторых командах документацию пишут специальные люди, которые ходят от разработчика к разработчику и от менеджера к менеджеру, аккумулируя знания о продукте.

Во многих небольших командах таких специальных людей нет, а потому документацию часто пишет разработчик или разработчики. Кто-то использует сторонние средства вроде Help
get
<
return Impl. Ascent ;
>
>

Блендер вместо 6 программ. Тайные возможности Blender

Очень полезным (и, к сожалению, часто игнорируемым) является тег 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 ) ;
>

Если вы хотите в описании одного метода дать ссылку на другой метод или тип, то нужно использовать конструкцию вида Текст ссылки , где X – необязательный префикс, обозначающий тип сущности (T для класса, M для метода, P для свойства, O для группы перегруженных методов), а MEMBER – полная или частичная спецификация сущности. Частичную спецификацию и отсутствующий префикс можно использовать, например, для ссылок между двумя методами одного класса или между двумя сущностями одного пространства имен (namespace).

Пример использования частичной спецификации (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: , что вполне терпимо.

• Recommended Tags for Documentation Comments (C# Programming Guide)
  msdn.microsoft.com/en-us/library/5ast78ax.aspx
• XML Documentation Comments Guide (Детальное руководство с примерами)
  www.dynicity.com/products/XMLDocComments.aspx
• XML документация в C#
  habrahabr.ru/blogs/net/41514
• C# and XML Source Code Documentation
  www.codeproject.com/KB/XML/csharpcodedocumentation.aspx?msg=1679454

Генерируем файл документации

1. Скачать и установить Sandcastle
   sandcastle.codeplex.com
2. Скачать и установить Sandcastle Help File Builder
   shfb.codeplex.com
3. Скачать и применить патч для стилей, используемых Sandcastle
   sandcastlestyles.codeplex.com
4. Если у вас возникнут проблемы со сборкой документации в формате HTML Help, то нужно проверить, что itircl.dll присутствует в системе и зарегистрирована. Обычно эта dll лежит в System32, регистрировать ее нужно через regsvr32. Подробнее написано тут:
   frogleg.mvps.org/helptechnologies/htmlhelp/hhtips.html#hhc6003

• секция 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.

• Подробное описание настроек SHFB
  www.codeproject.com/KB/cs/SandcastleBuilder.aspx
• Обзор SHFB на ХабраХабре
  habrahabr.ru/blogs/net/68227
• Сравнение Sandcastle и DocProject
  stackoverflow.com/questions/319632/docproject-vs-sandcastle-help-file-builder-gui

Пишем статьи

Однако не стоит останавливаться на достигнутом – одного описания 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-е (лог от предыдущего билда можно открыть в текстовом редакторе).

Для вставки кода в статью используется тег . Например:

< code language = «cs» >
private void helloWorld ( )
<
Console. WriteLine ( ”Hello World ! ” ) ;
>

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

1. В окне Project Explorer выбираем Add, потом Existing Item и выбираем нужную картинку.
   
2. В свойствах добавленного файла меняем BuildAction на Image, а свойство ImageId – на удобное название (будет использоваться в ссылках на это изображение).
   

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

К сожалению, в текущей версии SHFB редактор далек от совершенства. Например, теги не закрываются автоматически, очень много действий приходится делать мышью (нет хоткеев), не для всех стандартных тегов есть соответствующие элементы на тулбаре. Парадоксально, но мне для большинства действий с aml-файлами удобнее использовать Visual Studio. Разумеется, можно использовать и любой другой удобный xml-редактор для написания статей.

• Обзор MAML формата
  davesexton.com/blog/blogs/blog/archive/2008/05/24/maml-migration-the-next-step-in-the-evolution-of-help-authoring.aspx
• Подробное описание MAML формата
  sandcastlestyles.codeplex.com/releases/view/17333
• Различные примеры оформления документации с помощью SHFB
  www.codeproject.com/KB/winhelp/SandcastleConceptual.aspx
• Как создавать статьи из HTML, а не MAML
  habrahabr.ru/blogs/net/68227
• Как вставлять диаграммы классов в документацию
  habrahabr.ru/blogs/net/73790

Интеграция в процесс сборки

Можно включить файл проекта (*.shfbproj) от Sandcastle Help File Builder в solution Visual Studio, однако в настоящее время нет возможности использовать его как полноценный проект. То есть вы не сможете увидеть содержимое такого проекта, проект лишь добавится в группу Solution Items.

Добавление осуществляется следующим образом:

1. Для solution выбираете Add->Existing Item…, добавляете проект документации. Будет добавлен в папку Solution Items.
2. Щелкаете по добавленному элементу правой кнопкой мыши и выбираете Open With… В открывшемся диалоге добавляете ”Sandcastle Help File Builder GUI” и устанавливаете его в качестве редактора по умолчанию.

После этого проект документации можно будет открывать из Visual Studio.

Более полезна сборка документации из командной строки. Такую сборку можно делать на Post-Build event или в других случаях. Собрать документацию из командной строки очень просто следующей командой:
%SystemRoot%Microsoft.NETFrameworkv3.5MSBuild.exe» /p:Configuration=Release Help.shfbproj
В этой строке Help.shfbproj – название проекта документации.

Надеюсь, эта статья поможет вам начать писать документацию к вашим проектам (если вы еще этого не делаете) за что ваши пользователи наверняка скажут вам спасибо. Успехов вам в написании документации!

Источник: habr.com

Обзор основных возможностей программы

Audacity — это бесплатный звуковой редактор, который по своей функциональности может сравниться с профессиональными обработчиками звука, но значительно проще в использовании и освоении. Аудиоредактор создан в мае 2000 года, и начиная с этой даты миллионы пользователей по всему миру, установили данное приложения на свои компьютеры.

Программа переведена на многие языки мира, в том числе и русский, поэтому освоение и использования этого софта русскоязычными пользователями, осуществляется в течение очень короткого промежутка времени. Подробное описание программы и её возможностей будет изложено ниже.

Основные особенности программы:

• Запись с микрофона, линейного входа и других источников.
• Подходит для оцифровки старых записей.
• Импорт и экспорт файлов в форматах wav, mp3, aiff, au, и ogg;
• Широкий набор функций для редактирования аудио файлов.
• Воспроизведение множества дорожек одновременно.
• Детальный анализ частотных характеристик и спектрографический режим отображения дорожек.

Возможности программы

Среди наиболее востребованных функций программы можно назвать следующие:

· Загрузка и выгрузка файлов WAV и МР3.

· Запись звука с микрофона и линейного входа звуковой карты.

· При работе программы в режиме записи имеется возможность прослушивать уже записанные дорожки.

· При наличии звуковой карты поддерживающей многоканальную запись возможно одновременно подключить до 16 входящих каналов.

· В комплекте поставки имеется множество эффектов и расширений.

· Возможность использования плагинов сторонних разработчиков.

· Возможность контролирования уровня записи и воспроизведения.

· Изменение темпа и высоты звука.

· Сведение записанных дорожек с автоматическим преобразованием по заданным параметрам, а также в режиме реального времени.

· Сохранение аудиофайла в различных форматах.

· Изменить характеристики записанного голоса, в том числе, сделать красивый голос.

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

Как вырезать фрагмент (кусок песни), а также как склеить несколько файлов или как соединить песни, будет подробно описано в данной статье.

Дополнительные плагины

Учитываю некоторые нюансы законодательства США, в программное обеспечение не могут быть установлены дополнительные плагины, но пользователь может самостоятельно осуществить несложные действия по установке дополнений для Аудасити.

Плагины, которые могут быть установлены в Аудасити:

· VST Enabler — позволяет использовать в аудиоредакторе высококачественные ЭФФЕКТЫ для обработки аудиозаписи.

· Lame MP3 encoder — плагин позволяет сохранять аудиозаписи в формате mp3.

· Ambience VST Reverb — высококачественный ревербератор.

· Vocalremover — удаляет вокал из музыкальной композиции.

· FFmpeg — применение данной библиотеки в Аудасити позволяет сохранять и загружать файлы AC3, AMR(NB), M4A и WMA, а также извлекать аудиофайлы из видео.

Перечисленные расширения вместе с основным функционалом программы, позволяют осуществлять редактирование аудиофайлов на профессиональном уровне.

Системные требования

Звуковой редактор Аудасити не требователен к техническим ресурсам вычислительной техники. Для успешной работы необходимо чтобы компьютер работал под управлением операционной системы Windows начиная с версии ХР.

Программа имеет версии для установки как для 32 битной системы, так и для 64 бит. Существует также Аудасити для установки на macos и портативная версия, которую не требуется инсталировать на компьютер. В этом случае, достаточно скачать файл с аудиоредактором на съёмный носитель и Аудасити можно будет легко перенести на любое устройство, на котором установлена подходящая операционная система.

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

Обзор основных возможностей программы

Наиболее часто задаваемые вопросы по работе с аудиоредактором Audacity:

«Как соединить два трека» и «Как обрезать и соединить музыку», а также «Как работать в программе Audacity.

Чтобы сократить время звучания музыки необходимо воспользоваться специальным инструментом программы.

Процесс удаления лишних звуковых данных аналогичен работе в любом текстовом редакторе. Для того чтобы удалить определённый участок музыкальной композиции, его следует предварительно выделить.

Это действие в программе аудасити выполняется в такой последовательности:

1. На границу удаляемого участка наводится указатель мыши.

2. Нажимается и удерживается левая кнопка мыши.

3. Указатель перемещается до другой границы удаляемого участка аудиозаписи.

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

При этом произойдет автоматическое соединение участков аудиозаписи оставшихся после удаления фрагмента.

Соединение двух файлов можно осуществить следующим образом:

1. Загружаем файлы с использованием функции «Импортировать», которая находится в меню «Файл».

2. Затем выделяем участок второго файла, который необходимо переместить, и нажимаем Ctrl+C.

3. Устанавливаем указатель мыши на участок первого файла нажимаем Ctrl+V.

Предварительно скопированный файл автоматически установится в точку, которая была обозначена.

Как соединить две песни теперь понятно, а для сохранения музыку следует произвести действия описанные в следующем разделе.

Как сохранить музыку

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

1. В меню «Файл» выбрать «Exportaudio».

2. В открывшейся вкладке необходимо задать имя и тип файла.

3. Нажать кнопку «Сохранить», после чего аудиофайл сохранится в указанной папке.

Если необходимо сохранить аудиопроект, с которым планируется работать, то выполняются аналогичные действия, но в меню «Файл» выбирается опция не «Exportaudio», а «Сохранить проект». Как сохранить песню разобрались, но

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

Как убрать шум

Подавление шума в Аудасити осуществляется в 2 этапа:

1 этап: На графике выделяется участок записи, где находится только шум.

Затем необходимо открыть в верхнем меню «Эффекты» и выбрать опцию «Подавление шума». В открывшемся окне следует нажать на кнопку «Создать модель шума».

2 этап: На графике полностью выделяется аудиозапись. Затем снова открываются Эффекты — Подавление шума.

В открывшемся окне необходимо нажать кнопку «ОК», после чего программа в автоматическом режиме осуществит удаление шума из выделенной записи.

Если интересует вопрос: «Как убрать эхо на аудиозаписи», то данный недостаток решается таким же образом, как и при избавлении трека от лишнего шума.

Понравилась статья? Добавь ее в закладку (CTRL+D) и не забудь поделиться с друзьями:

Рекомендуем для прочтения:

Методы исследования Связь методики с другими науками. Методика как практическая дисциплина Методика есть практическая дисциплина.
ОСНОВНЫЕ ДВИЖЕНИЯ. МЕТОДИКА ОБУЧЕНИЯ Основные движения определяются как жизненно необходимые движения, используемые человеком в своей многообразной деятельности.
Стадии совершения преступления: понятие, виды, значение Под стадиями совершения умышленного уголовного преступления в уголовном праве понимаются предусмотренные УЗ определенные этапы его.
Факторы, влияющие на успешность обучения студентов Успех любой деятельности, в том числе и учебной, в первую оче­редь зависит от уровня интеллектуального развития.
НОРМАННСКАЯ КОНЦЕПЦИЯ И ЕЕ КРИТИКА Норманнская концепция (норманизм) — это одна из теорий возникновения Древнерусского государства.

Источник: studopedia.ru