Какой софт использовать для документации проекта

@Никлаус · Регистрация: 10.06.2019

Подскажите пожалуйста, пишу оконное приложение, с использованием СУБД Firebird, которое нужно задокументировать.
Пробовал doxygen, но он не видит private методы (возможно это можно как то исправить, но я пока что не нашел), и как я понимаю он больше подходит для консольных приложений (или я ошибаюсь).
Так что возможно у кого то был опыт документации оконных приложений, и он мне подскажет что использовал для документирования.

@Почтальон · 15.08.2019, 10:41

Чем не нравится стандартные методы документирования в VS ?

@Igr_ok · 15.08.2019, 10:42

Для студента этого должно хватить) https://docs.microsoft.com/en-... rp/codedoc

@kolorotur · 15.08.2019, 11:42

Сообщение от Никлаус

Пробовал doxygen, но он не видит private методы

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

@m0nax · 19.08.2019, 21:28

обычные XML комментарии единственный православный путь, да и то не везде - для библиотек или АПИ хорошо..
а для обычного внутреннего кода известно правило - нужны комментарии? код надо переписать чтоб были не нужны
если для паразитов манагеров у которых зачесалось одно место и надо что-нибудь куда-нибудь документировать для вида или препода - можно какую-нибудь красивую, но совершенно бесполезную схемку сгенерировать студией или решарпером, добавить воды с терминами и отстанут

@kolorotur · 19.08.2019, 23:03

Сообщение от m0nax

нужны комментарии? код надо переписать чтоб были не нужны

Зачем так категорично?
Не всегда имеется возможность сделать код самодокументируемым: существуют такие неприятные вещи, как реализация обратной совместимости, оптимизации, работа с кривыми сторонними API, да банально сам по себе сложный алгоритм для решения сложной задачи.
Комментирование кода — благое дело, когда используется правильно.

@Никлаус · 20.08.2019, 13:41 **[ТС]**

Всем спасибо, решил использовать Sandcastle Help File Builder (SHFB).
Мы делаем документацию для того, что бы наши последователи могли быстро войти в курс дела, поддерживать и допиливать продукт.
p.s. Мы - два студента, которые переписывают с delphi на c# цепочку ПО, которая используется в бухгалтерии.

Добавлено через 2 минуты
Т.к мы студенты которые перешли только на 3й курс, мы мало знаем, и код у нас мягко говоря так себе. Учитывая то что с c# мы были лишь немного знакомы в начале нашей работы (с того момента прошло всего лишь полтора месяца), конечно в каких то местах он будет не понятен и не логичен, так что в том числе и для этого тоже нужна документация.

@Никлаус 0 / 0 / 0 Регистрация: 10.06.2019 Сообщений: 95
		1
	Какой софт использовать для документации проекта 15.08.2019, 10:10. Показов 1685. Ответов 6 Метки базы данных (Все метки) Подскажите пожалуйста, пишу оконное приложение, с использованием СУБД Firebird, которое нужно задокументировать. Пробовал doxygen, но он не видит private методы (возможно это можно как то исправить, но я пока что не нашел), и как я понимаю он больше подходит для консольных приложений (или я ошибаюсь). Так что возможно у кого то был опыт документации оконных приложений, и он мне подскажет что использовал для документирования. 0

@Почтальон управление сложностью 1687 / 1300 / 259 Регистрация: 22.03.2015 Сообщений: 7,545 Записей в блоге: 5
	15.08.2019, 10:41	2
	Чем не нравится стандартные методы документирования в VS ? 0

@Igr_ok 783 / 615 / 272 Регистрация: 04.08.2015 Сообщений: 1,707
	15.08.2019, 10:42	3
	Для студента этого должно хватить) https://docs.microsoft.com/en-... rp/codedoc 0

@kolorotur 17096 / 12569 / 3301 Регистрация: 17.09.2011 Сообщений: 20,822
	15.08.2019, 11:42	4
	Сообщение от Никлаус Пробовал doxygen, но он не видит private методы Закрытые члены — это деталь реализации, они и не должны быть в документации. Документация пишется для тех, кто будет использовать ваши классы — им никакого дела до закрытых членов нет. Если надо задокументировать закрытые члены для тех, кто будет поддерживать ваши классы, то это делается комментариями прямо в коде. 0

@m0nax 1270 / 971 / 113 Регистрация: 12.01.2010 Сообщений: 1,971
	19.08.2019, 21:28	5
	обычные XML комментарии единственный православный путь, да и то не везде - для библиотек или АПИ хорошо.. а для обычного внутреннего кода известно правило - нужны комментарии? код надо переписать чтоб были не нужны если для паразитов манагеров у которых зачесалось одно место и надо что-нибудь куда-нибудь документировать для вида или препода - можно какую-нибудь красивую, но совершенно бесполезную схемку сгенерировать студией или решарпером, добавить воды с терминами и отстанут 0

@kolorotur 17096 / 12569 / 3301 Регистрация: 17.09.2011 Сообщений: 20,822
	19.08.2019, 23:03	6
	Сообщение от m0nax нужны комментарии? код надо переписать чтоб были не нужны Зачем так категорично? Не всегда имеется возможность сделать код самодокументируемым: существуют такие неприятные вещи, как реализация обратной совместимости, оптимизации, работа с кривыми сторонними API, да банально сам по себе сложный алгоритм для решения сложной задачи. Комментирование кода — благое дело, когда используется правильно. 0

@Никлаус 0 / 0 / 0 Регистрация: 10.06.2019 Сообщений: 95
	20.08.2019, 13:41 [ТС]	7
	Всем спасибо, решил использовать Sandcastle Help File Builder (SHFB). Мы делаем документацию для того, что бы наши последователи могли быстро войти в курс дела, поддерживать и допиливать продукт. p.s. Мы - два студента, которые переписывают с delphi на c# цепочку ПО, которая используется в бухгалтерии. Добавлено через 2 минуты Т.к мы студенты которые перешли только на 3й курс, мы мало знаем, и код у нас мягко говоря так себе. Учитывая то что с c# мы были лишь немного знакомы в начале нашей работы (с того момента прошло всего лишь полтора месяца), конечно в каких то местах он будет не понятен и не логичен, так что в том числе и для этого тоже нужна документация. 0

Опции темы