📑 Дока для кода

Простейший способ быстро вспомнить, как пользоваться этим классом / методом, который ты написал год назад - описать его. Побочным (и, кажется, неплохим) эффектом является то, что другой хороший программист тоже сможет пользоваться созданным тобой кодом. Поэтому, пожалуйста, рассказывай о своём коде так, чтобы потом, глядя на него, не было томительно больно.

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

Минимальная версия

/// Этот класс делает то-то.
class MyCoat {
    ...
}

Расширенная версия

/**
\brief Этот класс делает то-то.
\details
Здесь мы рассказываем, что этот класс
делает то-то-то-и-даже-это, а ещё
приводим примеры его использования.
\. (см. табличку ниже)
*/ 
class MyCoat {
    ...
}

Подобное оформление комментариев делай и для методов, и для свойств класса, и для функций, и для перечислений... Короче, для всего, что в комментариях _нуждается_!

Вместо \. _можем_ писать

Команда	Что делает
\code, \endcode	Пример использования.
\since	С какой версии 3DCoat появилось это чудо.
\todo	Что неплохо бы сделать, но, блин, как же времени не хватает!
\warning	Предупреждаем об опасностях!

See Also: Больше команд Doxygen

Мы стараемся называть классы, функции и переменные Хомо-понятными именами, а наша IDE довольно продвинута и умеет быстро рассказать об используемых типах. Поэтому, будьте лаконичны, комментируйте _по делу_.

See Also: Руководство по Doxygen

💑 Моменты

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

Платформа для документации - Doxygen.
Доксиджен майнит доку в папку output из папки документации/source и папок проектов.
Документация хранится в GIT-репозитории.
Пути - относительные. Поэтому, чтобы в _локальной_ документации появились ссылки на классы 3DCoat и других проектов Пилгвей, все репозитории должны лежать в **одной папке** под **теми же названиями**, что в хранилище проектов.
Файлы документации - это просто текстовые файлы, несмотря на расширение *.doc. Поэтому открываем их простым текстовым редактором.
Сегодня онлайн-дока обновляется мной _вручную_. Поэтому, друг, сделав коммит, наберись терпения... или набери меня.

👓 Посмотри, как выглядит твоя документация

Бывает, нужно черкнуть нечто более сложное, чем plain-текст. Например, выдать формулы. Или проверить, линкуется ли упомянутый нами класс / функция / макрос. Или ахнуть, как смотрится наш полезный коммент в формате Markdown.

Хотя визуализацию и Латеха, и Маркдауна можно глянуть онлайн, у Doxygen имеются ещё таблицы и много других вкусностей, реализация которых... отличается от "стандартов".

Что делать?

Клонируй себе репозиторий документации в *ту же папку*, где лежит проект 3DCoat.
Устанавливай Doxygen на свою машину.
Запускай файл build Doxy.cmd из папки build и жди: скоро откроется браузер с обновлённой докой.

Впрочем, при желании "поработать руками" (в Пилгвей это ценится), запусти Doxywizard и дай ему файл Doxy. Doxy легко найдёшь в папке клона (см. п. 1).

Дальше - разберёшься, ты умный)

Верно: с документацией можно работать также, как с кодом 3DCoat и любым доступным тебе GIT-репозиторием! Например, если можешь помочь другим, добавь себя на страницу Контакты. Для этого открой файл source/Contacts.doc из папки с документацией в своём любимом текстовом редакторе, запиши себя и сделай коммит.

Сделай это **сейчас**, чтобы убедиться: да, я могу!

P.S. Если что-то не получается *долго*, ты уже знаешь о странице контактов)

🌦 Проблемы и пути

На случай, если _никто_ из ребят (девочек нет, увы) помочь тебе не смог, читаем туториал ниже.

Кракозябры при открытии файла *.doc

Будь проще, используй простой редактор.

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

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

Также, чтобы ускорить сборку и обновление доки онлайн, в ней отсутствуют недокументированные** классы и методы.

Хороший стимул документировать свой код, не так ли?)

Документацию обновил, а в Интернете её нет

На сегодня, онлайн-дока обновляется два-три раза в неделю. Просто сделай свой master-коммит, всё будет!)

Серьёзно, никто-никто не смог помочь? Брат, оторвись от экрана!
Поверь и проверь: так будет больше пользы и тебе, и другим.