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

[kuzulis]

Доброго дня!

1. Как правильно в исходном коде оформлять комментарии, описания методов и т.п.?
например я делаю так в файлах реализации (*.срр):

Код:

/*! \fn int MyClass::method1(int param1) const
	\private - тут указываю из какой секции метод (public, private, protected ...)
	\brief - это краткое описание назначения метода
\en		- тут на английском назначение
\ru		- тут на русском назначение
	\param param1 - тут входные параметры
\en - на англ
\ru - на русском
        \return int - тут возвращаемое значение
\en - описание возвр знач на англ
\ru - описание возвр знач на русск
*/
int MyClass::method1(int param1) const
{
тут реализация метода
}

2. Где почитать про принятые стандарты ТЭГОВ в таких случаях
3. Для чего используются тэги?

ЗЫ: поделитесь, народ, кто как оформляет исходники: чтобы было красиво, удобно, понятно, и на нескольких языках

[UVV]

imho, посмотреть в сторону doxygen. И ещё imho, комментарии должны быть только на английском.

[navrocky]

А это чей язык разметки комментариев был использован? Местами очень напоминает doxygen.

[UVV]

А это чей язык разметки комментариев был использован? Местами очень напоминает doxygen.

Да, кстати

[kuzulis]

А это чей язык разметки комментариев был использован? Местами очень напоминает doxygen.
Да, кстати

Мой + чей-то еще + QTшный

[navrocky]

Вопрос не в тему, никто не знает чем qtшники генерят свою красивую документацию?

[BRE]

Вопрос не в тему, никто не знает чем qtшники генерят свою красивую документацию?

http://www.prog.org.ru/topic_7944_0.html

[kuzulis]

imho, посмотреть в сторону doxygen. И ещё imho, комментарии должны быть только на английском.

хм, но в настройках Doxyfile можно выставить параметр:

Код:

OUTPUT_LANGUAGE        = Russian

и тогда дока сгенерится на русском языке, НО!!! Какие нужно использовать тэги для разделения описания функций, классов, методов и т.п. на поддерживаемые Doxygen языки?

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

[UVV]

Я имел ввиду в принципе.

[lit-uriy]

>>И ещё imho, комментарии должны быть только на английском.
>>Я имел ввиду в принципе.
В принципе коментарии должны быть:
1) На своём родном, если ты уважаешь себя и свой язык.
2) Если тебе за коментарии платят, то на том языке за который платят.
3) Если тебе за коментарии не платят, но ты надешся кому-то угодить, то на том языке, для кого пытаешся угодить.

[Rcus]

Мне кажется что документацию и на одном языке то сложно держать актуальной, а на двух и подавно (и более полезными все равно оказываются более общие описания работы системы, форматов данных и подобное в отдельном документе)
Первый способ который можно попробовать это параметризованные альясы file://///usr/share/doc/doxygen/html/custcmd.html (apt-get install doxygen-doc )
Второй способ - держать полные копии, управлять генерацией через препроцессор.
Кстати OUTPUT_LANGUAGE влияет только на язык констант в доках.

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

[kuzulis]

В принципе коментарии должны быть:
1) На своём родном, если ты уважаешь себя и свой язык.
2) Если тебе за коментарии платят, то на том языке за который платят.
3) Если тебе за коментарии не платят, но ты надешся кому-то угодить, то на том языке, для кого пытаешся угодить.

+500

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

Первый способ который можно попробовать это параметризованные альясы file://///usr/share/doc/doxygen/html/custcmd.html (apt-get install doxygen-doc )

мда, в арче такого нету.. хотя посмотрю ща...

например имею это:

Код:

/*! 
\fn int fun(int param1) const
\brief
\lang <тут например тэг RU (или Russian)>
 тут описание функции на русском
 бла бла бла
\endlang
\lang <тут например тэг EN>
 тут описание функции на английском
 бла бла бла
\endlang
...
...
*/

Как бы так настроить Doxygen, чтобы например при установке OUTPUT_LANGUAGE = Russian - он выдирал только то, что заключено в тэги

Код:

\lang RU
....
\endlang

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

ЗЫ: неудобно как-то Doxygen сделан... не для всех!
ЗЫЗЫ: шоли патч написать? Или разрабу письмо паслать?

----

ЗЫЗЫЗЫ: послал письмо разработчику dimitri@stack.nl ждем чо ответят

[kuzulis]

Заработало!!!

Пример:

файл *.cpp

Код:

...
/*! \fn TPerunCore::TPerunCore()
	\brief
	\lang_Russian
	Конструктор по умолчанию
	\endlang
	\lang_English
	Default constructor
	\endlang
*/
TPerunCore::TPerunCore()
{
}
...

теперь в конфиге Doxyfile пишем:

Код:

...
OUTPUT_LANGUAGE        = Russian
...
ALIASES                = "lang_English=\if english" \
                         "lang_Russian=\if russian" \
                         "endlang=\endif"
...
ENABLED_SECTIONS       = russian
...

и документация + комменты будут собираться на русском !!!

- если нужно доку на англицком а комменты на русском - то делаем только: OUTPUT_LANGUAGE        = English
- если нужно доку на русском а комменты на англицком то делаем только: ENABLED_SECTIONS       = english

Оказывается все просто!

[Igors]

В принципе коментарии должны быть:
1) На своём родном, если ты уважаешь себя и свой язык.

Видимо так же думал один испанский программист чью программу мне пришлось однажды переделывать. Он много писал о какой-то "perdida" а я никак не мог понять что это    С кириллицей хуже, ее у заказчика может просто не быть. Так что при всем уважении к нашему языку, plain English - оптимальный вариант.

В реальном проекте (без open sources) каждый день 5-10 новых функций появляется и столько же убивается. Охота возиться с примечаниями для каждой пропадает очень быстро. Имеет смысл комментировать:

- члены класса (данные)  
- немногие специфические или сложные функции (обычно in/out)
- поддерживаемые форматы

[BRE]

В реальном проекте (без open sources) каждый день 5-10 новых функций появляется и столько же убивается. Охота возиться с примечаниями для каждой пропадает очень быстро.

IMHO!
Это для "реального" проекта с количеством участников == 1 (и то позднее вернуться к проекту без документации значительно сложнее чем с документацией).
Если участников > 1, то без нормальной документации развивать и сопровождать проект становиться невозможно.

Если каждый день убивается 5-10 функций:
* для проекта с количеством участников == 1 - нужно учится проектировать;
* для проекта с количеством участников > 1 - нужно увольнять архитектора.