Генерация исходной документации C# для НЕпрограммистов

Question

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

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

Есть ли простой способ документировать наш код с использованием метода /// и doxygen таким образом, чтобы, если мы запустим его определенным образом, мы могли сгенерировать документ, который ТОЛЬКО содержит версию документации по системному проектированию, без всякой дополнительной ерунды стандартную документацию для программистов, которая отпугнет системного специалиста, например, методы, переменные-члены и т. д.?Любые альтернативные предложения решения также приветствуются.

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

Answer 1

Одна вещь, которую вы можете сделать, это использовать doxygen \page команда, которая дает вам «Связанные страницы».Создайте текстовый файл с расширением, которое обрабатывается doxygen, и просто поместите туда комментарий.(Я использую .doc, но вы можете изменить его на что-то другое, чтобы не путать его с документами Word.Я также помещаю эти файлы в общий каталог под названием docsrc чтобы они были в одном месте.) Затем эти страницы отображаются в отдельном разделе документации.

/*!      
\page foobar Foobar calculation

I am using the procedure outlined in the bla bla note to estimate
the foobar in our baz. Lorem ipsum dolor...

\section step1 1. Estimation of the foobar-efficiency of the baz system.

\author jdm
*/

Затем вы можете создавать ссылки на страницу или разделы с помощью \ref foobar или \ref step1.

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

Answer 2

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

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

Answer 3

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