JavaDoc — зачем нам нужен этот кот?

Наполняем документацию смыслом

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

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

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

Настройте представление, генерирующее ссылки на требования

Каждый элемент (и даже результат запроса) в Cradle может иметь свой URL.  Чтобы однозначно адресоваться на элемент, надо указать сервер, проект, тип доступа (запись/чтение), уникальный ID, версию и признак драфта.

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

view_with_URL

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

Скопируйте ссылку на требование

Копирование выполняется из контекстного меню Еще->Копировать текст элемента->Имя фрейма ( в данном случае Multiple)

copy_multiple

Вставьте скопированную ссылку на требование в комментарии в коде

Просто вставьте скопированную ссылку в комментарии для javadoc

links_in_code

Автоматически получите ссылки на требования в документации javadoc

С помощью всего одного копирования и вставки мы автоматически получили ссылки на требования из Cradle в Javadoc.

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

javadoc-reqs

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

Эти ссылки — живые. Если кликнуть в javadoc, например, на NFR-1 , то будет открыто именно это требование в веб-интерфейсе Cradle и можно будет получить более детальную информацию по нему

req_in_weba

 

Дополнительно

Сгенерированное представление можно опубликовать, например, в html и передать программисту, если у него по какой-то причине нет доступа к базе требований в Cradle.

Используйте для этого функцию Опубликовать таблицу

publish_table

Результат:

published_table

 

Опубликовано в:

Добавить комментарий