s2t что это документация

Recent Posts

Categories

About Source to Target (S2T) Document or Mapping Document

S2T document is the bible of any ETL Projects. This will be designed by the Data Modeler’s using the FSD’s (Functional Specification Documents).

Data Modeler’s are interested in

Most of the S2T’s are written in Excel spread sheet. Where you will find many columns, each column is important for the ETL Load to be designed.

Major components of an S2T,

using the Version Numbers.

SourceDatabase– Source Database name or names will be mentioned in this space

Source Column– All the Source columns from respective Source Database are mentioned in this space (these columns will undergo the transformations if required.

Extraction Criteria– As I already mentioned, we are not going to pull all the data from the source before transformation however we need to pull the data that we required for the transformation and this will be mentioned in this space. All the Joins and Unions will be done here so as a Tester we need to understand and analysis this area with more care.

Example – Now I wanted to load Customers details and their balance from Savings account. Customers Details will be fetched from Cust_Detl table and the Balance from ACCT_BALANCE table, so you need to perform join in between. This extracting filters only Customers Savings account. So I consider this is my Data extraction criteria.

Filter Criteria– After we extracted the data from the source we need to filter the data if required for few or more target tables and this will be covered in this space.

Target Database – Target Database name or names will be mentioned in this space

Target Column – All the Target columns from respective Target Database are mentioned in this space (these columns will undergo the transformations if required.

Key or Value Columns–Next to the Target Column names you could see Key / Value. Key column means the column that makes the record unique and Value means, what makes the record time variant.

Comments and Version Changes – This space will explain us what was in the S2T before and what changed now. Comments will tell us more about the transformation.

What we need to look in the S2T?

As soon as you get the S2T, please query your Staging Source tables and check the data that you have got will satisfy your transformation rule. S2T’s will be written with the SIT phase data, and the rules mentioned might change as soon as we get the UAT Phase data. So to achieve the good quality of testing we always interested in UAT data.

Most of us will confuse the below transformation logic

Example: If the source columns are NOT NULL BLANK SPACE 0 and DO NOT LOAD the record. In this case, we might look for the record in the target when it has Unknown values.

Thanks for reading – Comments are Expected 🙂

Источник

Документация

Преобразуйте S-параметры в T-параметры

Синтаксис

Описание

Эта функция использует следующее определение для T-параметров:

a ₁ является инцидентной волной в первом порте.

b ₁ является отраженной волной в первом порте.

a ₂ является инцидентной волной во втором порте.

b ₂ является отраженной волной во втором порте.

Примеры

S-параметры к T-параметрам

Преобразуйте S-параметры в T-параметры. Задайте матрицу S-параметров.

Преобразуйте в T-параметры

Ссылки

Смотрите также

Представлено до R2006a

Документация RF Toolbox

Поддержка

© 1994-2019 The MathWorks, Inc.

1. Если смысл перевода понятен, то лучше оставьте как есть и не придирайтесь к словам, синонимам и тому подобному. О вкусах не спорим.

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

4. Не имеет смысла однотипное исправление перевода какого-то термина во всех предложениях. Исправляйте только в одном месте. Когда Вашу правку одобрят, это исправление будет алгоритмически распространено и на другие части документации.

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

Источник

State & Transition Diagram — что это и как применять

State & Transition Diagram (сокращенно S&T) — схема состояний и переходов. Техника для визуализации ТЗ. Она наглядно показывает, как некий объект переходит из одного состояния в другое.

Вот объект находился в состоянии А, потом произошло какое-то действие, и он попал в состояние В. Потом он попадет в состояние С и другие. Принцип не меняется, было одно состояние, стало другое.

кружочки — состояния объекта;

стрелочки — то, благодаря чему из состояния А в состояние В. Это действие, но его может совершить не только пользователь, но и система сама. Например, задача запустилась автоматически в 10 часов вечера.

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

Схема состояний и переходов относится к техникам тест-дизайна. Значит, про неё спрашивают на собеседованиях. И поэтому я сделаю небольшой цикл статей по таким техникам в помощь начинающим тестировщикам. Чтобы ознакомиться с каждой техникой:

State & Transition Diagram (схема состояний и переходов) — текущая статья

Сегодня поговорим про State & Transition Diagram:

Как рисовать диаграмму

Очень важно: S&T рисуется на объект! Один объект. В идеале — на объект, имеющий аналог в базе данных продукта.

Шаг 1. Вы выбираете объект в своём проекте (рабочем или учебном, не суть).

Шаг 2. Думаете, какие у него состояния. Они не должны пересекаться, то есть: объект не может быть разом в двух состояниях, и при этом он всегда хоть в каком-то одном есть

Шаг 3. Рисуете эти состояния кружочками.

Шаг 5. Смотрите, что получилось и анализируете, есть ли у объекта другие состояния? А другие действия между текущими состояниями? Переход на шаг 2.

Кто не будет выполнять эту последовательность шагов, очень рискует вместо S&T нарисовать схему вышивки крестиком)))

Чтобы начать, задайте себе вопросы:

Какой конкретно объект вы выбрали? Как он называется? (только один!)

Какие у этого объекта есть состояния?

Основное определение состояния — «набор доступных и недоступных действий с объектом». Продукт всегда должен знать, в каком состоянии каждый его объект. Вообще, когда будете думать об объектах и состояниях, старайтесь представлять их аппаратную реализацию.

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

Вот пример хорошей диаграммы:

State Transition на примере тортика!

В чатике моей школы для тестировщиков был очень интересный диалог по поводу рисования State Transition. Студентка рисует его для просмотра сериала и пытается разобраться, как это сделать:

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

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

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

— По-хорошему у тестировщиков на это есть права) и им дают необходимый доступ.

— То есть важны состояния только по отношению к сайту, а что там с этим сериалом происходит в аккаунте уже считается как одно — просмотр? Тестировщик я без году неделя, а пользователь — много лет 🙂 Поэтому и прошу постановки мозгов.

Тут моя коллега решила объяснить рисование карты на примере. Тортика! Дальнейший диалог был просто потрясающий, не могу не поделиться им с вами (разумеется, с разрешения коллеги, все же это ее идея, а не моя). Итак, приступаем:

— Вот смотрите. Торт любите? Или другую еду какую-нибудь)

Чтобы приготовить торт, нам нужны ингредиенты, правильно? Это то, из чего он состоит. Как и наши объекты из параметров, но только в граммах.

Так вот, от того, что какого-то ингредиента будет больше/меньше, состояние торта не изменится. Он будет по-прежнему «не существует».

Чтобы его состояние изменилось — надо начать что-то с ними делать. Например, смешать, залить в форму и отправить в духовку. Тогда состояние будет «В процессе готовки».

Потом, когда бисквит испечется, мажем его кремом и украшаем. Он становится у нас «Торт украшен».

Но сразу есть его нельзя, мы ставим в холодильник, чтобы украшение застыло, а только потом мы можем его есть. После холодильника состояние становится «Торт готов». А вот дальше — разнообразие)

Мы можем съесть торт, тогда он станет «Торт съеден».

Возможно, мы уедем и не съедим торт, пока его можно есть. Тогда он станет «Торт испорчен».

Кстати, в процессе приготовления могли быть и другие ответвления. Например:

— передержали бы бисквит, состояние изменилось бы на «Торт испорчен»;

— не стали бы украшать бисквит и корж испортился бы → «Торт испорчен»;

— Ну тут-то я, получается, покупаю готовый торт. И уже размышляю, что с ним делать.

— Ок, изначально торта у Вас не было. Потом у Вас появилось состояние «Торт куплен». А дальше то, что происходит после «Торт готов» ¯\_(ツ)_/¯

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

— То есть, я правильно понимаю?

2. Поставила в холодильник на потом

3. Передумала, достала, надкусала

4. Снова передумала, решила съесть целиком, осилила половину

5. Расстроилась и решила не доедать вообще и выкинуть

Это всё не важно и состояние торта не меняется, пока он не съеден или не стух?)

— Ну он же еще является тортом? Если его начали есть, но не закончили — можно ввести промежуточное состояние «В процессе уничтожения» =))

1-2 это торт куплен

3-4 это в процессе уничтожения

— Тогда чем это отличается от

1. Купила — добавлен на сайт/загружен на сайт/находится на сайте

2. Поставила в холодильник на потом — сохранен, чтобы посмотреть позже

5. Расстроилась и решила не доедать вообще и выкинуть — просмотр прерван/торт в помойке

— 5-е он еще в процессе.

У сериалов обычно прогресс есть, и его просто так не убрать 🙂

— либо он в процессе просмотра

Примеры S&T

Примеры диаграмм можно посмотреть в конфлюенсе (доступ открытый без авторизации). Туда я выношу хорошие работы своих студентов. Их там сильно больше, чем в этом разделе статьи + обычно там можно и сам исходник скачать, чтобы внимательно всё рассмотреть. Welcome =)

Вот некоторые из этих работ:

Ольга (объект — тест)

Кристина (Fallout Shelter)

Fallout Shelter — игра под iOS, Android. В постапокалиптическом мире несколько людей было выбрано для создания светлого будущего. Их поместили в небольшое убежище, уходящее под землю. Это убежище необходимо развивать, защищать от угроз из внешнего мира, увеличивать количество жителей, производить ресурсы, выполнять квесты.

State Transition для пина в Pinterest

Типовые ошибки при составлении карты

На примере своих студентов мы собрали несколько типовых ошибок, которые допускают тестировщики, впервые рисуя карту:

1. Вместо объекта — GUI

Очень важно: S&T рисуется на объект! Это не зарисовка графического интерфейса «открыта страница такая, открыта страница сякая». Если вы описываете разные странички GUI — это уже не S&T.

Зарисовывать страницы смысла обычно нет. Это как при рисовании майнд-карты — мы не рисуем графический интерфейс, мы описываем функционал. То, зачем пользователь вообще пришел на сайт. Это намного полезнее!

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

2. Несколько объектов в одной карте

На прошлой картинке у нас несколько объектов: результаты поиска, форма, данные. И все — плохие. Потому что там мы явно что-то покупаем, вот это «что-то» и есть объект!

Но когда мы описываем покупку, тоже легко скатиться в несколько объектов в одной карте: «пицца в корзине», «заказ оформлен».

Товар тоже очень часто путают, потому что есть два варианта:

как на авито — продается конкретная вещь: «Нет на сайте», «Продается», «Продан».

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

Если речь о сайте типа авито, то объект лучше выбрать «объявление», будет логичнее. А вот если мы покупаем пиццу — это будет товарной позицией.

3. Несколько одинаковых состояний

Вспомните пример с тортиком:

Поставила в холодильник на потом.

Передумала, достала, надкусала.

Снова передумала, решила съесть целиком, осилила половину.

Расстроилась, решила не доедать вообще и выкинуть.

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

1-2 это торт куплен;

3-4 в процессе уничтожения;

Другой пример — объект «пин»:

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

Но, когда пин откомментирован или сдублирован — это тоже самое, когда он просто создан. Состояние самого пина не меняется!

товар найден при поиске

Одно и то же с точки зрения товара. Он как был, так и есть.

Плюсы подхода

Плюс рисования — это визуализация ТЗ, которая:

Позволяет увидеть, что мы упустили

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

И пока мы рисуем его маршрут, мы можем сразу же заметить, что «Ага! Вот из этого состояния, наверное, можно вернуться ещё вот в это», то есть мы можем понять, что упускаем. А если бы не нарисовали, то даже не додумались бы до такого теста!

Минусы подхода

Не всегда визуализация делает ТЗ понятнее. И тогда начинаем думать, как это решать:

Слишком насыщенная карта — разбиваем на несколько маленьких.

Сложно поддерживать — нужна ли она вообще?

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

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

Не стоит рисовать все-все-все стрелочки. Из любого состояния можно закрыть браузер, но не надо рисовать это. Просто держите в уме, что есть кнопка «закрыть», а еще может интернет пропасть, или сервер упадет, или еще какая катастрофа случится.

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

Инструменты для рисования

Xmind (freemind, etc)

Основной инструмент — ручка и бумага, или маркер и доска. Потому что если вам надо просто обсудить, что будет, «если из этого состояния перейти в это, и как должна система реагировать, если происходит вот то», то вполне достаточно нарисовать это от руки.

К тому же от руки получается быстрее, а иногда еще и красивее. Почему? Потому что когда мы начинаем использовать инструмент, то он нас ограничивает. Вот, нам надо нарисовать стрелочку, так, а как нам это сделать. Мы начинаем думать в стиле инструмента. Это как когда мы создаем презентации в power point, то вместо мыслей о докладе думаем, как бы назвать новый слайд.

А если бумажка рядом, можно спокойно генерить в голове идеи и условия. Что придумал? Зарисовал кое-как. Если очень хочется, потом перерисовал красиво. А, может, и так сойдет.

В любом случае смотрите сами. Если удобен какой-то инструмент — используйте его! Хорошо получаются такие схемы в Xmind или Yed, или в гуглодокументах. Попробуйте использовать несколько разных инструментов, а потом выберите тот, что больше по душе. Но в целом бумага и ручка вполне себе вариант!

Итого

Рисунок — мощнейший инструмент визуализации. Вот вы открываете статью с картинками, типа этой. На что вы смотрите в первую очередь — на картинку или на текст? Правильно, на картинку.

Поэтому я за то, что рисовать! Нарисовали? Добавили в ТЗ! Всем удобнее, даже заказчику. Ведь с картинками текс становится понятнее.

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

Зарисовали, позвали аналитика и стали обсуждать:

— А вот смотрите, вот эта стрелочка. может нам стоит сделать еще вот это?

— А что будет, если вот так?

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

См также (напомню ссылочки):

Как составлять вариант использования — вариант оформления требований без рисований.

Источник

Расширение файла S2T

Scia2Tekla Plugin

Что такое файл S2T?

Программы, которые поддерживают S2T расширение файла

Программы, обслуживающие файл S2T

Как открыть файл S2T?

Причин, по которым у вас возникают проблемы с открытием файлов S2T в данной системе, может быть несколько. Что важно, все распространенные проблемы, связанные с файлами с расширением S2T, могут решать сами пользователи. Процесс быстрый и не требует участия ИТ-специалиста. Приведенный ниже список проведет вас через процесс решения возникшей проблемы.

Шаг 1. Установите Tekla Structures software программное обеспечение

Шаг 2. Проверьте версию Tekla Structures software и обновите при необходимости

Если проблемы с открытием файлов S2T по-прежнему возникают даже после установки Tekla Structures software, возможно, у вас устаревшая версия программного обеспечения. Проверьте веб-сайт разработчика, доступна ли более новая версия Tekla Structures software. Иногда разработчики программного обеспечения вводят новые форматы вместо уже поддерживаемых вместе с новыми версиями своих приложений. Если у вас установлена более старая версия Tekla Structures software, она может не поддерживать формат S2T. Последняя версия Tekla Structures software должна поддерживать все форматы файлов, которые совместимы со старыми версиями программного обеспечения.

Шаг 3. Свяжите файлы Scia2Tekla Plugin с Tekla Structures software

Если у вас установлена последняя версия Tekla Structures software и проблема сохраняется, выберите ее в качестве программы по умолчанию, которая будет использоваться для управления S2T на вашем устройстве. Следующий шаг не должен создавать проблем. Процедура проста и в значительной степени не зависит от системы

Процедура изменения программы по умолчанию в Windows

Процедура изменения программы по умолчанию в Mac OS

Шаг 4. Проверьте S2T на наличие ошибок

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

1. Проверьте S2T файл на наличие вирусов или вредоносных программ.

Если S2T действительно заражен, возможно, вредоносное ПО блокирует его открытие. Сканируйте файл S2T и ваш компьютер на наличие вредоносных программ или вирусов. Если сканер обнаружил, что файл S2T небезопасен, действуйте в соответствии с инструкциями антивирусной программы для нейтрализации угрозы.

2. Убедитесь, что структура файла S2T не повреждена

Если файл S2T был отправлен вам кем-то другим, попросите этого человека отправить вам файл. Возможно, файл был ошибочно скопирован, а данные потеряли целостность, что исключает доступ к файлу. При загрузке файла с расширением S2T из Интернета может произойти ошибка, приводящая к неполному файлу. Попробуйте загрузить файл еще раз.

3. Проверьте, есть ли у вашей учетной записи административные права

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

4. Проверьте, может ли ваша система обрабатывать Tekla Structures software

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

5. Проверьте, есть ли у вас последние обновления операционной системы и драйверов

Регулярно обновляемая система, драйверы и программы обеспечивают безопасность вашего компьютера. Это также может предотвратить проблемы с файлами Scia2Tekla Plugin. Устаревшие драйверы или программное обеспечение могли привести к невозможности использования периферийного устройства, необходимого для обработки файлов S2T.

Вы хотите помочь?

Если у Вас есть дополнительная информация о расширение файла S2T мы будем признательны, если Вы поделитесь ею с пользователями нашего сайта. Воспользуйтесь формуляром, находящимся здесь и отправьте нам свою информацию о файле S2T.

Источник

Документируем код эффективно при помощи Doxygen

Данная статья входит в получившийся цикл статей о системе документирования Doxygen:

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

Введение

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

Рассматриваемая система Doxygen как раз и выполняет эту задачу: она позволяет генерировать на основе исходного кода, содержащего комментарии специального вида, красивую и удобную документацию, содержащую в себе ссылки, диаграммы классов, вызовов и т.п. в различных форматах: HTML, LaTeX, CHM, RTF, PostScript, PDF, man-страницы.

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

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

Установка и настройка

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

Далее работа с Doxygen весьма тривиальна: достаточно запустить программу, указав ей путь к файлу с настройками.

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

В принципе, для редактирования данного файла и, вообще, работой с Doxygen, можно воспользоваться программой Doxywizard, которая чаще всего идёт вместе с Doxygen и которая позволяет чуть удобнее работать с файлом настроек (слева – Doxywizard; справа – файл открытый в текстовом редакторе):

Итак, приступим к созданию файла с настройками. Вообще, если вы используете Doxywizard, то он будет создан автоматически, в противном случае для создания этого файла необходимо запустить программу Doxygen с ключом -g (от generate):

Рассмотрим основные опции, которые могут вам пригодится, чтобы создать первую вашу документацию:

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

Для её генерации можно воспользоваться Doxywizard (для этого необходимо указать рабочую директорию, из которой будут браться исходные коды, перейти на вкладку «Run» и нажать «Run doxygen») или запустив программу Doxygen, указав ей в качестве параметра путь к файлу с настройками:

Основы документирования на Doxygen

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

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

Разница между ними чуть более сильная, чем между однострочным и многострочным комментарием. Дело в том, что текст, написанный в однострочном блоке относится к краткому описанию документируемого элемента (сродни заголовку), а текст, написанный в многострочном блоке относится к подробному описанию. Про эту разницу не следует забывать.

Многострочный блок

Мы сказали, что любой блок – это комментарий, оформленный специальным образом. Поэтому необходимо определить каким таким «специальным образом». Вообще, существует целый ряд способов для описания многострочного блока, и выбор конкретного способа зависит от ваших предпочтений:

При этом звездочки не обязательно ставить на каждой строке. Такая запись будет эквивалентной:

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

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

Для указания краткого описания может быть использована команда \brief. Указанный после команды текст, вплоть до конца параграфа будет относится к краткому описания, и для отделения подробного описания и краткого описания используется пустая строка.

Однострочный блок

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

При этом хотелось бы обратить внимание на два момента:

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

Да, Doxygen крайне гибок в плане способов документирования, однако не стоит этим злоупотреблять, и в рамках одного проекта всегда придерживайтесь заранее оговоренного единообразного стиля

Размещение документирующего блока после элемента

Во всех предыдущих примерах подразумевалось, что документирующий блок предварял документируемый элемент, но иногда бывают ситуации, когда удобнее разместить его после документируемого элемента. Для этого необходимо в блок добавить маркер «Угловые скобки показывают, что аргумент представляет собой одно слово(. )Круглые скобки показывают, что аргументом является весь текст вплоть до конца строки, на которой размещена командаФигурные скобки показывают, что аргументом является весь текст вплоть до до следующего параграфа. Параграфы разделяются пустой строкой или командой-разделителем

Кроме того, обратите внимание на то, что вы можете создавать и собственные команды. Подробно об этом можно прочитать в соответствующем разделе документации.

Документирование основных элементов исходного кода

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

Документирование файла

Хорошей практикой является добавление в начало файла документирующего блока, описывающегося его назначение. Для того, чтобы указать, что данный блок относится к файлу необходимо воспользоваться командой \file (причём в качестве параметра можно указать путь к файлу, к которому относится данный блок, но по умолчанию выбирается тот файл, в который блок добавляется, что, как правило, соответствует нашим нуждам).

Документирование функций и методов

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

Параметры

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

В результате мы получим такую вот аккуратную документацию функции:

Возвращаемое значение

Для описание возвращаемого значения используется команда \return (или её аналог \returns). Её синтаксис имеет следующий вид:

Рассмотрим пример с описанием возвращаемого значения (при этом обратите внимание на то, что параметры описываются при помощи одной команды и в результате они в описании размещаются вместе):

Получаем следующий результат:

Исключения

Для указания исключения используется команда \throw (или её синонимы: \throws, \exception), которая имеет следующий формат:

Простейший пример приведён ниже:

Документирование классов

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

Если ваш язык не поддерживает явным образом определенные концепции, такие как например уровни доступа или создание методов, но их наличие подразумевается и его хотелось бы как-то выделить в документации, то существует ряд команд (например, \public, \private, \protected, \memberof), которые позволяют указать явно о них Doxygen.

Документирование перечислений

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

То есть описание состояний указывается, собственно, после них самих при помощи краткого или подробного описания (в данном случае роли это не играет).

Результат будет иметь следующий вид:

Модули

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

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

Создание модуля

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

Идентификатор модуля представляет собой уникальное слово, написанное на латинице, который впоследствии будет использован для обращения к данному модулю; заголовок модуля – это произвольное слово или предложение (желательно краткое) которое будет отображаться в документации.

Обратите внимание на то, что при описании модуля можно дополнить его кратким и подробным описанием, что позволяет раскрыть назначение того или иного модуля, например:

Размещение документируемого элемента в модуле

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

Первый подход – это использование команды \ingroup:

Его недостатком является то, что данную команду надо добавлять в документирующие блоки каждого элемента исходного кода, поскольку их в рамках одного модуля может быть достаточно много.

Поэтому возникает необходимость в другом подходе, и второй подход состоит в использовании команд начала и конца группы: @ <и @>. Следует отметить, что они используются наряду с командами \defgroup, \addtogroup и \weakgroup.

Пример использования приведён ниже:

Смысл примера должен быть понятен: мы объявляем модуль, а затем добавляем к ней определенные документируемые элементы, которые обрамляются при помощи символов начала и конца модуля.

Однако, модуль должен определяться один раз, причём это объявление будет только в одном файле, а часто бывает так, что элементы одного модуля разнесены по разным файлым и потому возникает необходимость использования команды \addtogroup, которая не переопределяет группу, а добавляет к ней тот или иной элемент:

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

Наконец, команда \weakgroup аналогична команде \addtogroup, отличие заключается в том, что она просто имеет меньший приоритет по сравнению с ней в случае если возникают конфликты, связанные с назначение одного и того же элемента к разным модулям.

Создание подмодуля

Для создания подмодуля достаточно при его определении отнести его к тому или иному подмодулю, подобно любому другому документируемому элементу.

Пример приведён ниже:

Пример создания нескольких модулей

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

В результате мы получим следующую документацию:

Оформления текста документации

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

Код внутри документации

Зачастую внутри пояснения к документации необходимо для примера добавить какой-то код, например для иллюстрации работы функции.

Команды \code и \endcode

Один из наиболее простых и универсальных способов сделать это – команды \code и \endcode, которые применяются следующим образом:

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

Рассмотрим пример использования:

Результат будет иметь следующий вид:

Примеры кода

Иногда удобнее приводить примеры использования кода хранить в отдельных файлах. Для этого эти файлы необходимо разместить в отдельной директории и прописать к ней путь в настройках:

Рассмотрим, некоторые способы того, как примеры кода могут быть использованы в документации.

Команда \example
Данная команда показывает, что документирующий блок относится к примеру кода.

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

В данном примере, значение EXAMPLE_PATH = examples

Команда \include
Для того, чтобы добавить в описание к документируемому элементу код примера используется команда \include, общий формат которой имеет следующий вид:

Она полностью копирует содержимое файла и вставляет его в документацию как блок кода (аналогично оформлению кода в блок начинающийся командой \code и заканчивающийся командой \endcode).

Команда \snippet
Команда \snippet аналогична предыдущей команде, однако она позволяет вставлять не весь файл, а его определенный фрагмент. Неудивительно, что её формат несколько другой:

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

Автоматическое внедрение кода документируемого объекта

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

Формулы с использованием LaTeX

Doxygen позволяет использовать TeX формулы прямо в документации, это очень удобно и результат получается весьма достойным. Однако стоит отметить, что при этом имеются ограничения: на данный момент формулы могут быть вставлены только в HTML и LaTeX документацию, но этого, как правило, вполне достаточно.

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

Способы добавление формул в документацию

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

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

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

В итоге мы получим следующий результат (заметим, что окружение eqnarray* – это ненумерованное окружение для размещения нескольких формул):

Пример внедрения формул в документацию

Рассмотрим конкретный пример документации с использованием формул LaTeX:

Результат представлен ниже:

Кратко о Markdown

Markdown – это облегчённый язык разметки (почитать о нём можно, например, здесь, а также в специальном разделе в документации). Начиная с версии 1.8.0. Doxygen обеспечивает его пока ограниченную поддержку и он служит одним из способов оформить документацию (альтернативой могут быть, например, команды для оформления документации или HTML вставки, которые, впрочем, не универсальны).

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

Результат представлен ниже:

Подводя итоги

На этой ироничной ноте я решил остановиться. Я прекрасно понимаю, что ещё многое не было описано и затронуто, но, надеюсь, что главные свои цели статья выполнила: познакомить с понятием генератора документации, познакомиться с системой Doxygen, объяснить основные принципы и подходы к документации, а также мельком затронуть вопросы, связанные с её оформление и детализацией, подготовив задел для вашей дальнейшей работы.

Источник